# A role's version history + audit trail
Source: https://docs.tai42.ai/api-reference/access-control/a-roles-version-history-+-audit-trail

/openapi.json get /api/auth/roles/{name}/versions
The role's append-only version history plus its who/when/before→after audit trail.

Admin-only. A store-less deployment keeps no history, so the read is an empty pair.



# Add a URL to a scope
Source: https://docs.tai42.ai/api-reference/access-control/add-a-url-to-a-scope

/openapi.json post /api/auth/scopes
Map ``url`` to ``scope_id`` (optionally with a dynamic match ``pattern``).



# Add/remove scopes on an api key
Source: https://docs.tai42.ai/api-reference/access-control/addremove-scopes-on-an-api-key

/openapi.json post /api/auth/api-keys/{user_id}/scopes
Add and/or remove named scopes on a key's stored scope set without replacing the whole set.

The new set keeps the stored order, drops the removed scopes, then appends the additions in the given
order. A plain read-merge-write with NO new locking: two simultaneous edits of one key can lose one
(accepted for this surface).



# Create a one-time claim link for an API key
Source: https://docs.tai42.ai/api-reference/access-control/create-a-one-time-claim-link-for-an-api-key

/openapi.json post /api/auth/claim-links
Mint a one-time claim link that carries ``api_key`` to another device (the QR onboarding leg).

The submitted key is resolved through the gate's own verifier chain and the caller must own it
(or be admin) per the module's ownership rule; the response returns the claim token ONCE plus a
fragment-carrier path on the declared hosted-UI login page (``/login#claim=<token>`` by default)
and an expiry.

Accepted oracle (deliberate, not an oversight): an unresolvable key answers 400 and a
valid-but-not-yours key answers 403, so an authenticated caller can tell a live key
from garbage. This adds NO capability the ``/api/auth/me`` carve-out does not already
grant a caller holding a candidate key. The uniform-404 no-oracle rule governs the
unauthenticated EXCHANGE surface, never this authed creation.



# Create a principal
Source: https://docs.tai42.ai/api-reference/access-control/create-a-principal

/openapi.json post /api/auth/principals
Create a ``human`` or ``service`` principal and apply its role (admin only).

The door mints a ``user_id`` when absent. A duplicate id is a 409; an unknown role is a
400. ``created_by`` records the admin who created it.



# Create a role
Source: https://docs.tai42.ai/api-reference/access-control/create-a-role

/openapi.json post /api/auth/roles
Create an operator-authored role.

Admin-only; validates the grant map + base tier before persist; 409 on a name collision. Bumps
the policy version and audits.



# Create an api key
Source: https://docs.tai42.ai/api-reference/access-control/create-an-api-key

/openapi.json post /api/auth/api-keys
Provision a key, returning ``{"api_key", "key_fingerprint"}``.

The raw ``sk-…`` ``api_key`` is surfaced ONCE; ``key_fingerprint`` is the key's immutable per-mint
identity a caller binds a hook against so the binding survives only this exact mint.



# Delete a principal
Source: https://docs.tai42.ai/api-reference/access-control/delete-a-principal

/openapi.json delete /api/auth/principals/{user_id}
Delete a principal, revoking every key it owns plus its policy row (admin only).

Refused (409) when a login-owning accounts provider keeps a login record for the principal
— that provider's member actions on the Members page remove the principal and the record
together, so the record never outlives the principal. A principal no provider claims
(service, hand-provisioned OIDC human, keys-only owner) is deleted here; deleting the last
enabled admin principal is refused (409) by the last-admin guard. A missing principal is a
404.



# Delete a role
Source: https://docs.tai42.ai/api-reference/access-control/delete-a-role

/openapi.json delete /api/auth/roles/{name}
Delete a role.

Admin-only; the reserved ``admin`` role is undeletable; a role still assigned to any principal
(its LIVE pointer held by any policy) is rejected loudly so a holder can never be orphaned.
Bumps the version and audits.



# Delete a scope
Source: https://docs.tai42.ai/api-reference/access-control/delete-a-scope

/openapi.json delete /api/auth/scopes/{scope_id}
Delete a scope, cascading it out of every referencing key.

An unknown scope (no urls) is a loud 404.



# Edit a role's grant map
Source: https://docs.tai42.ai/api-reference/access-control/edit-a-roles-grant-map

/openapi.json put /api/auth/roles/{name}
Edit a role's per-tag grant map + description (the base-tier jq is seed-fixed, not editable here).

Admin-only; guards the reserved ``admin`` role and the block-downgrade of any allow_all role.
Both inputs are omit-means-keep — an absent ``grants``/``description`` preserves the stored
value, so a description-only edit never wipes the grant map. Validates a supplied grant map
before persist; LIVE — the edit changes every holder's reach on their next request via the
policy-version bump. Audits.



# Edit an api key
Source: https://docs.tai42.ai/api-reference/access-control/edit-an-api-key

/openapi.json put /api/auth/api-keys/{user_id}
A PATCH-style partial edit: only the fields present in ``updates`` are overwritten.

A field absent is preserved at its stored value, so saving a description or scope change never silently
drops an authorization ``condition`` or ``policy_data`` gate. ``updates`` is the sparse set of present
fields (a single dict rather than flattened params, so "field absent" stays distinct from "field is
``null``" — the partial-edit semantics a flat signature cannot express).



# Initialize the deployment (owner + first key)
Source: https://docs.tai42.ai/api-reference/access-control/initialize-the-deployment-owner-+-first-key

/openapi.json post /api/setup
Initialize the deployment once behind the secure-by-default setup-token gate.

Only meaningful on a serviceable access-controlled install: it refuses loudly with a
501 when the door cannot initialize — access control off, no configured key-minting
identity provider, or the access-control Redis unset. The per-IP backoff is consulted
BEFORE the token, so a wrong-token flood escalates a lockout that turns further attempts away
without ever comparing; a wrong/absent token is a generic 403 (no oracle for the
initialized state). Under one mint mutex: 409 "Already initialized" when ANY principal
exists; else the owner principal (``kind=human``) is created, granted the admin role,
its first key (owned by the owner) is minted and returned ONCE, and — when a configured
accounts provider can attach a login and the request carries one — the owner's login is
attached (a password set now, or an invite whose one-time link is returned). A failure
past the owner create is compensated so setup stays retriable; a correctable login
credential is compensated then mapped to the caller (a too-short password → 400, a
login/email collision → 409) rather than surfaced as a 500.



# Invoke a member action
Source: https://docs.tai42.ai/api-reference/access-control/invoke-a-member-action

/openapi.json post /api/auth/member-actions/invoke
Invoke one declared member action by its opaque key (admin only).

The key decodes to ``(provider, action_id)`` and the optional handle to the
``(provider, target)`` the action acts on; a malformed token or a key/handle naming
different providers is a loud :class:`BadRequestError`. The per-action ``input`` is
validated by ``input_model.model_validate`` (ordinary pydantic — a declared-field type
error is a 422, an unknown key is ignored). The provider's typed failure propagates and
the platform reads no field of the opaque result.



# List a user's policy version history
Source: https://docs.tai42.ai/api-reference/access-control/list-a-users-policy-version-history

/openapi.json get /api/auth/api-keys/{user_id}/policy/versions
The user's append-only policy version history from the durable PG store.

Each row is flagged ``is_current`` against the active pointer. Secret-adjacent (a version
body carries the raw condition) and admin-only: a non-admin caller is denied 403 so it can
never read another user's policy history. 404 when the user has no policy history.



# List all scopes
Source: https://docs.tai42.ai/api-reference/access-control/list-all-scopes

/openapi.json get /api/auth/scopes
Every non-public route mapping as ``{url: scope_id}``.



# List api-key token payloads
Source: https://docs.tai42.ai/api-reference/access-control/list-api-key-token-payloads

/openapi.json get /api/auth/tokens-payload
Every provisioned key's identity + policy (NEVER key material).

Non-admin callers see ONLY the keys they own (management/listing owner home); admin sees every key.



# List member actions
Source: https://docs.tai42.ai/api-reference/access-control/list-member-actions

/openapi.json get /api/auth/member-actions
The deployment-wide catalog of declared member actions (admin only).

Each registered accounts provider's :meth:`member_actions` declarations are serialized
into opaque-keyed :class:`MemberActionDescriptor` rows, the label resolved through the
resource manager and the input/result schemas rendered generically. The platform reads
no action field.



# List members and invites
Source: https://docs.tai42.ai/api-reference/access-control/list-members-and-invites

/openapi.json get /api/auth/members
Aggregate every registered accounts provider's people and invitations (admin only).

Each provider's :meth:`~tai42_contract.accounts.provider.AccountsProvider.list_members`
supplies its own members and invites; the aggregate wraps them into wire rows in provider
name order, minting each row's opaque handle and action keys and joining each member
principal's ``disabled`` state (the principal store, read once per call) and the role it
holds (one ``principal_roles`` read for every member principal). A member row's
``disabled`` is derived True only when EVERY principal is disabled; its ``role`` is the
one role every principal holds, else ``None``. Provider errors propagate (loud, never a
silently empty listing).



# List principals
Source: https://docs.tai42.ai/api-reference/access-control/list-principals

/openapi.json get /api/auth/principals
Every principal (admin only).



# List public-pinned routes
Source: https://docs.tai42.ai/api-reference/access-control/list-public-pinned-routes

/openapi.json get /api/auth/public-routes
Every route pinned to the public marker.



# List roles
Source: https://docs.tai42.ai/api-reference/access-control/list-roles

/openapi.json get /api/auth/roles
The seeded/operator-authored roles as full ``RoleDefinition``-shaped bodies.

Each body is ``{name, description, scopes, condition, base_tier, allow_all, grants}`` — the
Members page's role action and the Studio Roles page read this. A store-less deployment (no
versioned store configured) has no roles — the seed step is skipped at boot — so the read is
skipped and the list is empty.

Admin-only: a listing exposes every role's raw base-tier jq condition, so a non-admin
caller is denied 403. This op-level check is defense in depth behind the ``secret``
route action-class that already fences the route.



# List the app's HTTP routes and their scope mappings
Source: https://docs.tai42.ai/api-reference/access-control/list-the-apps-http-routes-and-their-scope-mappings

/openapi.json get /api/auth/routes
Enumerate the app's own HTTP routes with each route's current scope mapping.

Covers the mapper's route picker and its "unassigned routes" bucket (the ``mapped: null``
entries).

``routes`` is the app's live route table (the route-adapter extractor hands the
operation ``request.app.routes`` so it stays request-free). One entry per
:class:`starlette.routing.Route`, sorted by ``path``. ``Mount`` entries (the sub-MCP
mount, the MCP mount) are EXCLUDED — a mount is not a bindable url and the sub-MCP
surface has its own door. The exclusion is an explicit ``isinstance`` filter: any
route-table entry that is neither a ``Route`` nor a ``Mount`` raises loudly (a new
Starlette routing type must be classified here, never silently dropped). ``methods``
is the route's method set sorted with ``HEAD`` removed (Starlette auto-adds it to
every GET route — noise for the mapper). ``mapped`` is the url's value from
``get_all_route_mappings`` looked up by the EXACT path string — a scope id, the
public marker for a public pin, or ``null`` when the path has no mapping. Exact-key
lookup only: this door does not attempt dynamic-pattern matching.

``declared_public`` is ``True`` for a route public by its own declaration: it answers
everyone whatever scope it is mapped to (the access check's declared-public tier), so the
scope writer refuses to map it.

Each entry is JOINED with its :class:`RouteMetadata` (from
``route_registry.load_all_routes()``, a separate collection) to also carry the
route's feature ``tags`` + ``summary`` + authorization ``action`` — the data the
Studio Roles page groups the per-tag tri-state by and marks the ``fenced``/``secret``
(admin-only) routes it must never offer a grant for. The join is keyed on the route
TEMPLATE + its method set with ``HEAD`` stripped on BOTH sides (Starlette auto-adds
``HEAD`` to a GET), so the two collections compare like-for-like; a registered route
whose method set fails to join is a loud STOP (a normalization drift), never a
silently dropped row.



# Log out the current session
Source: https://docs.tai42.ai/api-reference/access-control/log-out-the-current-session

/openapi.json post /api/auth/logout
Revoke the caller's session by fanning ``revoke_session`` out over every candidate and provider.

Fans out over every presented credential candidate and every registered accounts
provider.

Iterating all candidates is required: a client may present a stale value in
``Authorization`` alongside its live session in ``X-Api-Key``, so checking only the
first would leave that session alive. The FIRST ``True`` → ``{"revoked": true}``.
Only when EVERY candidate against EVERY provider returns ``False`` → 404 (an
``sk-`` API key cannot "log out" — loud, not a silent no-op), with a server-side
log naming the caller so probing/replay stays visible. Provider errors propagate
(fail closed).



# Pin a route public
Source: https://docs.tai42.ai/api-reference/access-control/pin-a-route-public

/openapi.json post /api/auth/public-routes
Pin ``url`` public (optionally with a dynamic match ``pattern``).



# Remove a URL from all scopes
Source: https://docs.tai42.ai/api-reference/access-control/remove-a-url-from-all-scopes

/openapi.json delete /api/auth/scopes/urls
Unmap ``url`` from every scope that references it.

A url that was never mapped is a loud 404 (a typo, not a silent success).



# Report key-mint capabilities
Source: https://docs.tai42.ai/api-reference/access-control/report-key-mint-capabilities

/openapi.json get /api/auth/capabilities
Whether any configured identity provider can MINT keys, per provider.

Lets the Studio disable mint UI with a clear message on a validator-only deployment instead of
surfacing a raw error at mint time.



# Revoke an api key
Source: https://docs.tai42.ai/api-reference/access-control/revoke-an-api-key

/openapi.json delete /api/auth/api-keys/{user_id}
Revoke a key (immediate: next request fails to auth).

Deletes the key record, its enforced policy row, and its live context; the user's ``ac_policy`` version
history is deliberately NOT touched (it belongs to the identity, so a key later re-created
for the same ``user_id`` resumes that history).

No version bump here, unlike every other mutation on this surface: revocation's
cache-buster is atomic with the policy-row delete inside
:func:`~tai42_skeleton.access_control.management.revoke_api_key`, so no fault in the
steps behind it can leave the revoked key's authority live in a warm cache slot.



# Roll a policy back to a version
Source: https://docs.tai42.ai/api-reference/access-control/roll-a-policy-back-to-a-version

/openapi.json post /api/auth/api-keys/{user_id}/policy/rollback
Re-point the enforced policy to a prior version.

Store-first: the target version body is read from the history, written to the enforced store
(the authority) FIRST — the writer invalidates the policy cache — then the durable history
pointer is advanced. Admin-only: a non-admin
caller is denied 403 so it can never roll back another user's (or its own) enforced policy.
404 if the version is absent or the user has no live key.



# Roll a role back to a version
Source: https://docs.tai42.ai/api-reference/access-control/roll-a-role-back-to-a-version

/openapi.json post /api/auth/roles/{name}/rollback
Re-point a role's active version to a prior one (LIVE — holders follow on their next request).

Admin-only; the reserved ``admin`` role has no editable history. Bumps the version and audits.



# Set/remove single tag grants on a role
Source: https://docs.tai42.ai/api-reference/access-control/setremove-single-tag-grants-on-a-role

/openapi.json post /api/auth/roles/{name}/grants
Set (upsert) and/or remove single tag grants on a role WITHOUT replacing the whole map.

Admin-only; guards the reserved ``admin`` role and the block-downgrade of any allow_all role.
``upsert`` overwrites a tag's level (the one sanctioned overwrite); a ``remove`` tag absent from
the stored map is a loud 404. Validates the merged map before persist; LIVE via the
policy-version bump. Audits as ``edit``.



# The caller's capability projection
Source: https://docs.tai42.ai/api-reference/access-control/the-callers-capability-projection

/openapi.json get /api/auth/me
The authenticated caller's derived capability projection.

The concrete routes, dynamic patterns, sub-MCP mounts, tools, and agents it can reach right
now (derived, never stored).

``user_id``/``effective_scopes``/``claims`` are the caller's OWN identity, derived at
the HTTP edge from the authenticated request — never caller-supplied. This is
``caller_context=True`` (tier-1, never projectable): as an MCP tool a caller would
supply those identity params itself and read ANY principal's projection, so the HTTP
route (``/api/auth/me``, whose extractor derives them from ``request.user``) is the
only surface. With the gate OFF there is no identity to project (the edge passes
``user_id=None``), so a synthetic TOTAL projection is returned; otherwise the
projection is built through the REAL enforcer so it can never advertise a door the
gate would deny. Any infrastructure error propagates per the projection's failure
doctrine.



# Unpin a public route
Source: https://docs.tai42.ai/api-reference/access-control/unpin-a-public-route

/openapi.json delete /api/auth/public-routes
Unpin a public ``url``; a url that is absent or scope-mapped is a loud 404.



# Update a principal
Source: https://docs.tai42.ai/api-reference/access-control/update-a-principal

/openapi.json put /api/auth/principals/{user_id}
Update a principal's display name and/or disabled state (admin only).

Both fields are omit-means-keep. A ``disabled`` change is refused (409) when a
login-attaching accounts provider holds the principal's credential — its disabled state
lives with that provider and changes through its member actions on the Members page — and
otherwise flips both homes through the guarded disabled writer (a principal whose login
record a provider keeps without holding its credential is disabled here). Disabling the
last enabled admin principal is refused (409) by the last-admin guard. A display-name edit
is accepted for any kind. Returns the updated principal; a missing principal is a 404.



# Validate a jq policy condition
Source: https://docs.tai42.ai/api-reference/access-control/validate-a-jq-policy-condition

/openapi.json post /api/auth/validate-condition
Fail-closed guard: compile — and optionally sample-evaluate — a jq policy ``condition``, unpersisted.

A syntactically broken condition raises at enforcement and DENIES the key (a
lock-out), so authoring flows validate here before saving. The condition is
rendered through the SAME ``render_condition`` enforcement uses, compiled with
``get_compiled_jq``, and — when a ``sample_context`` is supplied — decided by the SAME
``PolicyEnforcer.evaluate`` against a ``JqAuthContext``-shaped sample, so the
validator's verdict is enforcement's by construction. This ONLY compiles/evaluates; it
never writes any store. Returns ``{"ok": true, "result": <bool|null>}`` (``result`` is
``null`` when no sample was evaluated).
An AUTHOR error is a loud ``BadRequestError`` (400); a server-side fault (an
unconfigured resource manager, a redis/storage outage rendering a stored condition
``id``) is NOT an author error and propagates as a loud 500.



# List every registered agent
Source: https://docs.tai42.ai/api-reference/agents/list-every-registered-agent

/openapi.json get /api/agents
List every registered agent with its schema and spec-runnable marker, plus a total.



# List the spec-runnable (authorable) agents
Source: https://docs.tai42.ai/api-reference/agents/list-the-spec-runnable-authorable-agents

/openapi.json get /api/agents/spec-runnable
Only the authorable agents (``spec_runnable`` True) — the compose UI's base-agent picker.

Filters on the marker, never on a known agent name; an empty list means no authoring
is possible.



# Stream a run of an agent
Source: https://docs.tai42.ai/api-reference/agents/stream-a-run-of-an-agent

/openapi.json post /api/agents/{name}/runs
Stream a run of the named agent as SSE; 404 for an unknown agent, retriable while a reload holds the gate.



# Stream a run of an authored agent
Source: https://docs.tai42.ai/api-reference/agents/stream-a-run-of-an-authored-agent

/openapi.json post /api/agents/authored/{name}/runs
Stream a run of an authored agent — a preset over an agent's run tool whose baked fields it honors.

The baked spec is read from the ``PresetManager`` in-memory map (the single
source of truth for every registered preset — versioning never gates
streamability). The request body supplies ONLY the remaining,
non-baked ``ToolInput`` fields; naming a baked field is a loud 400 rather than a
silent override. The baked fixed kwargs plus the request fields are combined at
the FIELD level, validated against the agent's ``ToolInput``, and mapped through
``from_tool_input`` before ``astream`` — never a raw splat that would bypass
validation and the field mapping.



# Get the backend identity
Source: https://docs.tai42.ai/api-reference/backend/get-the-backend-identity

/openapi.json get /api/backend
The backend identity — whether one is registered and, if so, its class and module.



# List the worker fleet
Source: https://docs.tai42.ai/api-reference/backend/list-the-worker-fleet

/openapi.json get /api/fleet/workers
The fleet listing — one row per live worker presence key, each with a server-computed ``stale`` flag.



# Soft-restart the worker fleet
Source: https://docs.tai42.ai/api-reference/backend/soft-restart-the-worker-fleet

/openapi.json post /api/fleet/reload-config
Soft-restart the worker fleet, optionally restricted to the named ``targets``.

Called over MCP on a worker the reload applies to (no ``targets``, or ``targets`` naming that
worker), the reload answers on the session that called it and then retires that session with the
generation it ran on: a later call on the same session fails (streamable HTTP answers it 404, and an
SSE session's stream closes), so the client starts a new session to go on. When ``targets`` leave
that worker out, nothing reloads there and the session keeps working.

Each worker's payload is ``{status, env_keys, awaiting_respawn}``: ``awaiting_respawn`` names the
recycle-class keys whose value now differs from the one that worker bound (at boot, or when the
plugin that declares them was loaded) — the soft
restart carries every hot key in place, and those keys take effect only when the worker is
respawned through the deployment's supervisor (on a bare deployment, a server restart). This
operation ERROR-logs one line naming every such worker and its keys.



# Export the named backup sections
Source: https://docs.tai42.ai/api-reference/backup/export-the-named-backup-sections

/openapi.json post /api/backup/export
Export the requested backup ``sections`` as a downloadable JSON document.

A failed section exporter is recorded under ``errors`` rather than aborting the export; a
malformed request body or an unknown section name is a loud 400.



# Import a backup document
Source: https://docs.tai42.ai/api-reference/backup/import-a-backup-document

/openapi.json post /api/backup/import
Import each SELECTED section of ``document`` in registration order and return a per-section report.

``mode`` is the per-record policy (``skip`` or ``overwrite``). A ``version`` other than 1
raises ``BadRequestError``; an unknown, absent, or failing section carries its error in
the report and makes ``ok`` false. A section whose restore rolled a worker recycle (an env
section changing a recycle-class key on a supervised deployment) carries the roll in its
``recycle``; when that roll converged, this worker recycles itself after replying.



# List backup sections
Source: https://docs.tai42.ai/api-reference/backup/list-backup-sections

/openapi.json get /api/backup/sections
List the registered backup sections as ``{name, secret}`` entries.



# List registered channels
Source: https://docs.tai42.ai/api-reference/channels/list-registered-channels

/openapi.json get /api/channels
The registered channel names ``ask(channel=...)`` can resolve.



# Sweep expired checkpoint threads
Source: https://docs.tai42.ai/api-reference/checkpoints/sweep-expired-checkpoint-threads

/openapi.json post /api/checkpoints/sweep
Delete the checkpoint threads of the deployment's store that are past their retention horizon.

A finished thread (marked by its owner) goes at the due time stored with its mark; on a store
whose waiting horizon is swept any thread goes its waiting retention (declared by its owner, else
``checkpoint_retention_waiting_minutes``) after its newest checkpoint (a store that expires it by
key TTL, or keeps it for the process, is reported in ``skipped``). A thread a registered
live-thread filter claims is spared and listed. ``waiting_minutes`` and ``finished_minutes`` in
the result are the platform's values: the default and ceiling of every thread's retention.



# Apply a settings profile — replace the stored env and reload the fleet
Source: https://docs.tai42.ai/api-reference/config/apply-a-settings-profile-—-replace-the-stored-env-and-reload-the-fleet

/openapi.json post /api/config/profiles/{name}/apply
Apply the profile's active env as the WHOLE stored env band and reload the fleet.

The profile's ``secret_keys`` are written as the stored secret marks in the same replace.

A key the profile omits is deleted, save the carried deployment X band; build+swap a fresh serving
epoch under it, persist env-write-LAST, broadcast the reload, and recycle the fleet for recycle-class
diffs. NO request body.

The response is the dedicated ``profileApplyResponse`` ``{hot, recycle:[{name, kind, status,
generation_before, detail}], fresh:[{name, kind, generation}], refused:[],
recycle_stopped:{kind, name, detail} | null, awaiting_respawn:[{name, keys}], fanout}`` — key names
+ worker identities only,
never env values. ``recycle`` is one line per sibling the roll reached (plus the applier's
own deferred self-exit line when it is armed). A ``recycled`` line is confirmed on reality;
the roll stops at the first line that is not: ``timed-out`` (its old life did not go, fresh
capacity did not boot, or it never returned to ready, within the step budget) or ``failed``
(the worker refused the op, or the bus could not be reached while it was in hand), its
``detail`` naming why — or when the bus could not be read before a target was reached.
``recycle_stopped`` names where the roll stopped and why (``null`` when it ran to its end; a
``null`` name when no target was in hand). Later siblings and the applier's own recycle are
then not attempted, and the call still answers with the report: the env is persisted and the
fleet reloaded. ``fresh`` is the per-kind new ready lives observed since the pre-apply
snapshot, capacity evidence never claimed as any target's successor. ``refused`` is ``[]``:
a refusal (X-band key, dangling ``!ENV``, a recycle-class diff the deployment shape cannot
carry) aborts upfront with a loud 400 naming the key, before anything is snapshotted, built,
or persisted. ``awaiting_respawn`` names the workers (name + keys) still awaiting a respawn
after the roll — empty when it converged. When the diff carries serve-affecting recycle keys
and the roll converged, the applier's OWN recycle is armed as a post-reply graceful self-exit
— after the HTTP body flushes, or once a projected tool call (MCP, ``tai tools run``, an
agent, a preset, a schedule, a hook) returned — and its supervisor respawns it on the new
env. 404 for an absent name.

Called over MCP, the reload answers on the session that called it and then retires that session with
the generation it ran on: a later call on the same session fails (streamable HTTP answers it 404,
and an SSE session's stream closes), so the client starts a new session to go on.



# Create or update a settings profile
Source: https://docs.tai42.ai/api-reference/config/create-or-update-a-settings-profile

/openapi.json put /api/config/profiles/{name}
Create the profile, or append a new version when it exists (whole-body replace).

Returns ``{ok: true, version}`` — NEVER the stored body, so a secret never re-emits on the write path.
A reserved ``@``-prefixed name is a loud 400. The profile's DECLARED env is run through the shared
boundary validator (``ConfigService._validate_replace``): a payload carrying an X-band key or leaving
a manifest ``!ENV`` marker dangling is refused at save time, naming the key.



# Delete a settings profile
Source: https://docs.tai42.ai/api-reference/config/delete-a-settings-profile

/openapi.json delete /api/config/profiles/{name}
Soft-delete the profile, keeping its version history (audit).

404 for an absent name.



# Diff a settings profile against the stored env
Source: https://docs.tai42.ai/api-reference/config/diff-a-settings-profile-against-the-stored-env

/openapi.json post /api/config/profiles/{name}/diff
The saved profile's env vs the CURRENT stored env, with REAL values (the UI masks) — a preview, not a report.

``added`` / ``removed`` are key names, ``changed`` is ``[{key, old, new}]``. ``recycle_keys`` are the
diff keys whose registry ``reload_class`` is ``recycle``; ``refused_keys`` are the diff keys the
recycle policy refuses upfront on this deployment shape
(``recycle_policy.capability_report().refused_keys``), named. 404 for an absent name.



# Get a settings profile
Source: https://docs.tai42.ai/api-reference/config/get-a-settings-profile

/openapi.json get /api/config/profiles/{name}
The profile's active body — ``{description, env, secret_keys}`` with REAL env values.

This authed ``secret``-fenced door round-trips values through the editor; masking is display-side only,
never on the wire. 404 for an absent name.



# Get a settings profile version
Source: https://docs.tai42.ai/api-reference/config/get-a-settings-profile-version

/openapi.json get /api/config/profiles/{name}/versions/{version}
One version row extended with its full ``body`` (REAL values — this door is ``secret``-fenced).

The body is ``{description, env, secret_keys}``. A non-integer segment is a 400, an unknown version
a 404.



# List a settings profile's versions
Source: https://docs.tai42.ai/api-reference/config/list-a-settings-profiles-versions

/openapi.json get /api/config/profiles/{name}/versions
The profile's version history as a bare array of ``{version, tags, created_at, is_current}`` rows — NO body.

404 for an absent name.



# List settings groups with their resolved field values
Source: https://docs.tai42.ai/api-reference/config/list-settings-groups-with-their-resolved-field-values

/openapi.json get /api/config/settings-schema
Return every registered settings group with per-field current values.

Each group carries the settings class' field metadata plus a ``value`` per
field, resolved with pydantic-settings precedence: ``os.environ`` wins (in
a non-file config mode an external provider injects vars the dotenv store never sees), then
the stored env override, then the shared ``TAI_DEFAULT_*`` namespace, then the
field default. Nested-group reference fields (``env_var == ""``) are non-editable
and report ``value: null``. Secret fields report their real value — this authed
surface round-trips values through the editor; masking is display-side only,
never on the wire.

Each field also carries ``value_source`` naming which layer supplied its
resolved ``value`` so a UI can badge provenance (notably "from default" for a
``TAI_DEFAULT_*`` fallback): ``"env"`` (process env), ``"stored"`` (the dotenv
override), ``"default_namespace"`` (a ``TAI_DEFAULT_*`` fallback, from process
env or the store), ``"field_default"`` (the bare field default), or ``null``
for a non-editable nested-group reference.

Only IMPORTED settings classes appear: in a running skeleton the kit,
skeleton, and manifest-loaded plugin modules — the intended scope.



# List settings profiles
Source: https://docs.tai42.ai/api-reference/config/list-settings-profiles

/openapi.json get /api/config/profiles
One ``{name, description}`` row per active settings profile, excluding reserved ``@``-prefixed snapshots.

Reserved snapshots include e.g. ``@previous``. A store-less deploy holds no profiles, so it serves an
empty list rather than opening an absent store.



# Merge env overrides and reload the fleet
Source: https://docs.tai42.ai/api-reference/config/merge-env-overrides-and-reload-the-fleet

/openapi.json post /api/config/env
Merge env overrides into the stored config and reload this worker and the fleet.

A hot-class key is re-read in place. A recycle-class key rolls a worker recycle across the
fleet on a supervised deployment: the response's ``recycle`` carries the roll's rows (``null``
when the change carried no recycle-class key), and when the roll converged this worker
recycles itself after replying — on the HTTP edge and on every projected tool door alike (a
post-reply graceful self-exit its supervisor respawns).
A change the deployment cannot carry is refused with a 400 before anything is written, naming
the key: a recycle-class key on a bare (unsupervised) deployment, and the bus URL or a key the
deployment pins on every shape.

``secret_keys`` (when not ``None``) replaces the operator's secret marks in the same write;
the marks variable itself is never accepted as an ``env`` key.

Called over MCP, the reload answers on the session that called it and then retires that session with
the generation it ran on: a later call on the same session fails (streamable HTTP answers it 404,
and an SSE session's stream closes), so the client starts a new session to go on.



# Read the active config backend mode
Source: https://docs.tai42.ai/api-reference/config/read-the-active-config-backend-mode

/openapi.json get /api/config/mode
Return the active config backend mode.



# Read the stored env config and secret-key marks
Source: https://docs.tai42.ai/api-reference/config/read-the-stored-env-config-and-secret-key-marks

/openapi.json get /api/config/env
Return the stored env map alongside the operator's secret-key marks.

``data.env`` is the stored env key-value map (a never-written store yields
an empty map). ``data.secret_keys`` is the DERIVED masked-key set
(:func:`~tai42_skeleton.settings.env_secret_marks.effective_secret_keys`): the
operator's stored ``TAI_ENV_SECRET_KEYS`` marks UNIONED with every live
``connectors[*].client_secret_env``, so an oauth connector's client secret is
masked on display even with no operator mark.



# Roll a settings profile back to a version
Source: https://docs.tai42.ai/api-reference/config/roll-a-settings-profile-back-to-a-version

/openapi.json post /api/config/profiles/{name}/rollback
Re-point the active version to ``version`` (no data copy), making it the current body.

Returns ``{ok: true, version}``. 404 for an absent name or version. A store-only re-point — the live
process is realigned by a later apply, not by this door.



# Soft-restart the process from its manifest
Source: https://docs.tai42.ai/api-reference/config/soft-restart-the-process-from-its-manifest

/openapi.json post /api/config/reload
Soft-restart the process from its manifest, in-process with no pod restart.

Refreshes env from the config manager, resets every settings cache, and re-initializes from the
manifest. Applied on this worker (when it is a target) and broadcast to the fleet (all workers, or only
``targets``); the response embeds the per-worker fleet report.

Heavy (a full re-init); meant for env/config saves, not tool edits. A convergence
op: its whole purpose is aligning siblings to persisted state, so a failed local
reload still broadcasts and then re-raises with the fleet report attached.

Called over MCP on a worker the reload applies to (no ``targets``, or ``targets`` naming that
worker), the reload answers on the session that called it and then retires that session with the
generation it ran on: a later call on the same session fails (streamable HTTP answers it 404, and an
SSE session's stream closes), so the client starts a new session to go on. When ``targets`` leave
that worker out, nothing reloads there and the session keeps working.

Each worker's payload is ``{status, env_keys, awaiting_respawn}``: ``awaiting_respawn`` names the
recycle-class keys whose value now differs from the one that worker bound (at boot, or when the
plugin that declares them was loaded) — the soft
restart carries every hot key in place, and those keys take effect only when the worker is
respawned through the deployment's supervisor (on a bare deployment, a server restart). This
operation ERROR-logs one line naming every such worker and its keys.



# Add an MCP server as a connector provider
Source: https://docs.tai42.ai/api-reference/connectors/add-an-mcp-server-as-a-connector-provider

/openapi.json post /api/connectors/providers
Add the MCP server at ``url`` as a discovered provider, written to the manifest and broadcast to the fleet.

Its id is ``provider_id`` or a suggestion from the host. An id that is not free — a provider in the
manifest, a stored connection record (live or lapsed), or a stored client row under it — is a 409
naming which; nothing is deleted.



# Complete an OAuth connection flow
Source: https://docs.tai42.ai/api-reference/connectors/complete-an-oauth-connection-flow

/openapi.json post /api/connectors/oauth/complete
Complete an OAuth connection flow, serving the discriminated ``/oauth/complete`` body.



# Disconnect a connection
Source: https://docs.tai42.ai/api-reference/connectors/disconnect-a-connection

/openapi.json delete /api/connectors/connections/{connection_id}
Disconnect (purge) a connection; a genuinely-absent connection is a 404.



# Get a connection
Source: https://docs.tai42.ai/api-reference/connectors/get-a-connection

/openapi.json get /api/connectors/connections/{connection_id}
One connection's secret-free view, with live sub-service reachability.

An unknown id is a loud 404.



# List connections
Source: https://docs.tai42.ai/api-reference/connectors/list-connections

/openapi.json get /api/connectors/connections
The installed connections as secret-free views.

``health`` filters the returned items to a single ``auth_health_state``
(``healthy`` / ``reconnect_required`` / ``refresh_failing``); an unrecognised
value is a loud 400. ``limit`` caps the number of returned items (a positive
integer no larger than the hard guard); ``total`` still reports the full match
count so a caller sees there is more beyond the page. ``unhealthy`` counts every
not-healthy connection across the whole set, independent of the filter and limit.



# List connector providers
Source: https://docs.tai42.ai/api-reference/connectors/list-connector-providers

/openapi.json get /api/connectors/providers
The provider catalog — one entry per registered connector provider, plus category groupings.

The category groupings are those the UI arranges the providers under.
Providers come from the in-memory registry (populated from the manifest's
``connectors`` list at boot/reload), so they list regardless of store
configuration; each says whether the provider door may remove it and where its
sign-in client comes from (``unset`` for a stored-client provider and never
removable while the store is not configured). The category
groupings live in the connector store's Postgres, so they are served only when
that store is configured (otherwise an empty grouping list, mirroring the
OFF-state connections read).



# Look up an MCP server's sign-in
Source: https://docs.tai42.ai/api-reference/connectors/look-up-an-mcp-servers-sign-in

/openapi.json post /api/connectors/providers/discover
Look up the sign-in of the MCP server at ``url``, or of the server of the discovered provider ``provider_id``.

Persists nothing. ``origin`` is the deployment origin a sign-in would start from: it decides the
callback address an app registered by hand must allow and whether this deployment's client-identity
document can serve the login. An unknown provider is a 404; a declared one a 400.



# Patch a connection's enabled sub-services
Source: https://docs.tai42.ai/api-reference/connectors/patch-a-connections-enabled-sub-services

/openapi.json patch /api/connectors/connections/{connection_id}/sub-services
Toggle a connection's enabled sub-services; an unknown id is a 404.



# Re-encrypt connector tokens and client credentials under the current KEK
Source: https://docs.tai42.ai/api-reference/connectors/re-encrypt-connector-tokens-and-client-credentials-under-the-current-kek

/openapi.json post /api/connectors/tokens/reencrypt
Re-encrypt every stored connector token and client credential under the current ``CONNECTORS_KEK``.

The KEK-rotation convergence sweep: after ``CONNECTORS_KEK`` is rotated (new current
key, old key moved to ``CONNECTORS_KEK_PREVIOUS``), this rewrites every connection blob
and every stored OAuth client blob still under a previous key so the previous key can
be retired. Idempotent — a blob already under the current key is skipped. A blob no
configured key can open is counted and named in ``failed_connection_ids`` /
``failed_client_row_ids``, never silently dropped. A missing/malformed
current ``CONNECTORS_KEK`` is a deployment-wide config fault and surfaces as a named
``NotSupportedError`` (501), never an unnamed 500.



# Remove a connector provider added by its address
Source: https://docs.tai42.ai/api-reference/connectors/remove-a-connector-provider-added-by-its-address

/openapi.json delete /api/connectors/providers/{provider_id}
Remove a removable provider and its stored clients.

A provider that is not removable here is a 409 naming where it is managed; a provider with a
LIVE connection is a 409 naming the count. A connection whose session has lapsed is purged first,
through the disconnect routine. The manifest change comes before the client rows are deleted, so a
failed change leaves them; a failed deletion after it is raised, and running the remove again
deletes the rows left under the id (nothing else holds it any more; no manifest change, so no
fan-out).



# Set the client credentials of a connector provider
Source: https://docs.tai42.ai/api-reference/connectors/set-the-client-credentials-of-a-connector-provider

/openapi.json put /api/connectors/providers/{provider_id}/client
Store the client credentials of an app registered by hand for the discovered provider ``provider_id``.

The credentials are stored for one sign-in service the provider's server lists: ``issuer`` when
given (400 when the server does not list it), else the one the provider's manual client is already
stored for while the server still lists it; with neither, a 400 ``connector-client-issuer-required``
naming the listed ones — the secret is never sent to a sign-in service nobody chose. Only a
discovered provider that names no env client takes stored credentials.



# Start a connection flow
Source: https://docs.tai42.ai/api-reference/connectors/start-a-connection-flow

/openapi.json post /api/connectors/connections/start
Begin a Connect (OAuth authorize URL, or an immediate no-auth connection).



# Start a reconnect flow
Source: https://docs.tai42.ai/api-reference/connectors/start-a-reconnect-flow

/openapi.json post /api/connectors/connections/{connection_id}/reconnect
Re-run the OAuth flow for an existing connection; an unknown id is a 404.



# Create or replace a conversation route
Source: https://docs.tai42.ai/api-reference/conversations/create-or-replace-a-conversation-route

/openapi.json post /api/conversations/{route_name}
Create a conversation route from its flat parameters — an UPSERT (create AND edit path).

``initial_mode`` is the route's default control mode (``agent`` runs the turn, ``manual``
suppresses it for an operator to answer) when a thread carries no per-thread override.

``target_name`` must merely EXIST — the agent (``target_kind=agent``) or tool
(``target_kind=tool``) — the key's live grants bound the turn at fire. ``execution_key`` is
the api-key identity the turn runs AS; the caller must be allowed to delegate it and it must
be usable by a tokenless fire. Both are decided at this door BEFORE the route write service
runs the route's own rules, so a refusal leaves any existing row untouched. The write service
runs the target's bind check (a refusal is a 422 carrying its lines), then renders and
compiles the door jqs (``start_expr``/``cancel_expr``/``resume_expr``/``extras_expr``) and
``reply_expr``, so an invalid one — or a by-id text whose stored resource cannot be fetched —
is refused at create, not at first message. A
``channel`` row's ``our_identity`` is stored canonicalized and must not already be routed
on that channel. An edit that would change the ``door`` of a route already HOLDING
threads is refused: the two doors key their threads differently, so the held threads
cannot be re-keyed under the new door.
An ``api`` row that declares a ``callback_url`` has its ``callback_secret`` minted by the
write and returned ONCE; a poll-only api row (no callback) mints none and reads its answers
back from the poll door. A positive
``turns_per_hour_override`` runs this route's per-address buckets at that rate instead
of the global ``per_address_turns_per_hour`` cap; ``None`` runs them at the global rate.
A ``reply_texts`` catalogue carries the route's own words for the platform's fixed
participant replies (a failed turn, the slow-down line, the pairing replies, the inbound
refusal notices), in the line's language; ``None`` or an unset member sends the built-in
English reply.
A ``locale`` is the operator-declared default language templated reply parts render in when
a turn supplies none; it is the last fallback under a per-turn or stored-contact locale and
is stored canonicalized. ``None`` declares no route default (bare/English).
An ``overlap`` policy governs how a running turn treats the newer participant messages that
overlap it (learn/cancel/carry); ``None`` stores the default policy (continue/one/no window),
which runs one turn per message and leaves the payload unchanged.
Returns ``{"created", "route_name", "route", "callback_secret"}``.



# Create or replace a conversation target config
Source: https://docs.tai42.ai/api-reference/conversations/create-or-replace-a-conversation-target-config

/openapi.json put /api/conversation-configs/{target_kind}/{target_name}
Create or replace the per-target config for ``(target_kind, target_name)`` — an UPSERT.

This is the create path AND the edit path for a config of that key.

The target must merely EXIST — the agent (``target_kind=agent``) or tool
(``target_kind=tool``) — exactly as the route create checks it. ``greeting_template``
may reference at most the ``{pairing_code}`` placeholder and a blank template is refused
(``null`` = no greeting), both enforced by the model. No key is bound and no authority
delegated: this is inert operator config. Returns
``{"created", "target_kind", "target_name", "config"}``.



# Delete a conversation person
Source: https://docs.tai42.ai/api-reference/conversations/delete-a-conversation-person

/openapi.json delete /api/conversations/persons/{person_id}
Erase a LINKED person and every person it absorbed by a link from the bridge's stores.

- the person's aggregated ``bridge:@person:{person_id}`` thread — its agent checkpoint,
  and across EVERY route the person wrote under (its addresses' routes and the routes its
  thread's writes recorded) its answer records, per-thread transcript indexes, route-thread
  index memberships and per-thread mode override (the thread-delete machinery, reused);
- for every person it absorbed by a ``/link`` (a chain flattened into it): that person's
  aggregated thread the same way;
- every route-keyed thread, on any route, that only the person and the persons it absorbed
  wrote in — its checkpoint, records, parks and ``thread``-subject state, exactly as a thread
  delete forgets it. The thread's records decide, read under its hold: a thread a record of
  another writer still stands in (another person, or an address nobody held when it wrote)
  is left to them, unless that person's own erase is running too, and nothing is written to
  a thread left;
- the declared state of the person and of every person it absorbed (``person``-subject and
  their aggregated threads' ``thread``-subject memory);
- the person row ``conversations:person:{person_id}``, its absorbed SET, the absorbed
  persons' pointers, their lists of the threads they wrote in, and every ``person_index``
  ``door_address_key → person_id`` mapping of its addresses.

The bridge's stores only: the interaction store's answered state hashes (which keep a request's
``recipient`` and a non-sensitive answer until their idle TTL) and the hook-runs store (whose
failed run can carry a participant's address in its event payload until an operator retries or
discards it) are not erased by it.

Caller authority is the door's grantable ``write`` action — the same grant that forgets a
thread. IDEMPOTENT and retryable: the erase first sets the person's erase mark under the
per-thread FIFO, and from then on every person write refuses the person, its addresses are
attributed as unlinked and its thread takes no new record; the person row is the durable marker
of an owed erase and is deleted LAST (atomically with its mark, its index mappings, its
absorbed SET and the lists of the threads they wrote in), so an interruption after the
teardown began leaves the row and the mark and a retry FINISHES. A refusal before the
teardown (a 409 or a 503) removes the mark first. A write by the person or a person it absorbed
that lands in a thread the erase had not reached, in its last moment, is a 409 after the
teardown: the mark stands, and a retry finishes the erase and clears that thread too. A retry,
or an id that was never a person, is not a 404 — its aggregated checkpoint is forgotten
regardless (it defaults to keep-forever) and the call answers ``erased=false``. An id a
``/link`` absorbed into another person is a 409 naming that person (``absorbed_into_person_id``), whose
erase clears it. A turn IN FLIGHT on a thread the erase clears is a 409 (retry once it drains),
re-checked under the thread's FIFO before its teardown so an admitted turn cannot re-create
memory behind the erase; a full queue is the retriable 503. As a
live-caller sync door every acquisition is bounded by ``sync_door_wait_seconds``: a wait past it
— behind a turn possibly HITL-paused on another worker, behind a turn on an absorbed person's
thread that holds its lock while it waits for a gate slot, or behind a ``delete-person`` call of
an absorbed id — is the loud, retriable 503 ``ThreadBusyError`` rather than a block past the
proxy timeout. A blank ``person_id`` is a 400; no backend is a loud 501.

Returns ``{"person_id", "removed", "erased", "states_erased", "absorbed_person_ids"}``, where
``removed`` counts the answer records this call deleted across the person's routes, in every
absorbed person's thread and in every route thread it cleared, ``erased`` says whether THIS call
removed the person row, ``states_erased`` counts the declared-state records forgotten for the person and every
absorbed person, the cleared route threads' ``thread`` subjects included, and
``absorbed_person_ids`` lists, sorted, the absorbed ids this call cleared.

A send still going out to one of the person's addresses keeps that address on its ``sending``
row until its completion, end or settle (at most one settle deadline), and ``removed`` does not
count it. A completion re-attributed once the erase has begun is placed without the person
link, in the route-keyed thread an inbound from that address would now start.



# Delete a conversation route
Source: https://docs.tai42.ai/api-reference/conversations/delete-a-conversation-route

/openapi.json delete /api/conversations/{route_name}
Delete a conversation route by name, along with the thread indexes it owned.

Those indexes carry no TTL and the prune pass only walks LIVE routes, so a delete that
left them behind would strand them unreachable forever; the answer records they name
keep their own retention TTL and are not touched.

The reclamation is RETRYABLE, because it can be interrupted (a socket timeout, a
SIGTERM, a Redis blip) after the routing row is already gone: a name whose route index
survives is one whose reclamation is still owed, so this door re-runs it and answers
``removed=false`` rather than the 404 that would leave those keys unnameable forever.
Only a name that neither routes nor owes reclamation is the loud 404. A name that is not
a valid slug is a 400. Returns ``{"removed", "route_name"}``, where ``removed`` says
whether THIS call removed the routing row.



# Delete a conversation target config
Source: https://docs.tai42.ai/api-reference/conversations/delete-a-conversation-target-config

/openapi.json delete /api/conversation-configs/{target_kind}/{target_name}
Delete the per-target config for ``(target_kind, target_name)``.

An unknown key is a loud 404; a malformed key is a 400. Returns ``{"removed", "target_kind", "target_name"}``.



# Delete a conversation thread
Source: https://docs.tai42.ai/api-reference/conversations/delete-a-conversation-thread

/openapi.json delete /api/conversations/{route_name}/thread
Forget ONE conversation thread: its agent checkpoint, its answer records and its thread indexes.

A later message on the same address starts a memory the deleted turns never touched. A LINKED
person's aggregated ``bridge:@person:{id}`` thread is forgotten across every route index it
spans.

Forgetting is ABSOLUTE: a valid id on its own route always succeeds, even when nothing is
stored. An aged-out thread whose answer records already expired under the retention TTL,
or one never seen, answers ``removed=0`` and never a 404 — and its checkpoint is deleted
regardless, because that memory defaults to keep-forever and is otherwise left behind once
the records lapse. A route-keyed id MUST carry the route's ``bridge:{route_name}:`` prefix;
an id belonging to another route is a loud 400, the sole guard stopping a delete on one
route from wiping another route's memory. A person ``bridge:@person:{id}`` thread whose
person is unknown, or whose ``route_name`` is not one of the person's routes, is a loud
404. A turn IN FLIGHT on the thread (an ``accepted`` intake still holding a live lease) is
a 409: its completion re-writes checkpoint state and re-stamps the indexes behind the
delete, half-forgetting the memory — retry once it drains. The guard is re-checked under
the FIFO, so a turn admitted while the lock is being taken is refused before any teardown,
never left to re-create memory behind the delete. A ``route_name`` that is not a valid
slug, or a blank ``thread_id``, is a 400.

Caller authority is the door's grantable write action — the SAME write grant that creates
a route deletes routes and forgets threads — never a per-thread owner check.

The teardown runs in an order an interruption cannot strand: the checkpoint FIRST — its
memory is reachable only through the indexes once this call returns, so it must go while
the indexes still name the thread to bring a re-run back — then the records and the indexes
together, the index being the durable marker of an owed reclamation and torn down LAST.
Idempotent under re-run, so a partial completion is FINISHED by a retry.

The whole teardown runs under the thread's per-thread FIFO (the lock an operator send and
an in-flight turn take), so an operator send already in flight on the thread within this
worker drains BEFORE the delete rather than half-behind it; a full queue is the loud,
retriable 503 that FIFO raises before anything is torn down. As a live-caller sync door the
acquisition is bounded by ``sync_door_wait_seconds``: a wait past it — behind a turn possibly
HITL-paused on another worker — is the loud, retriable 503 ``ThreadBusyError`` rather than a
block past the proxy timeout.

Returns ``{"removed", "route_name", "thread_id", "states_erased"}``, where ``removed`` counts
the answer records this call deleted (0 when a prior run already cleared them, when their rows
had expired under the retention TTL, or when the id was never stored) and ``states_erased``
counts the thread-subject declared-state records forgotten across the routes the thread spans
(0 when the states feature is off or the thread held no declared state).

A send still going out on the thread when this call runs is forgotten when it ends, not by
this call: for at most one settle deadline its ``sending`` row, in no thread index, still holds
the participant's address, and ``removed`` does not count it.



# Deliver a structured event to a conversation thread as a turn
Source: https://docs.tai42.ai/api-reference/conversations/deliver-a-structured-event-to-a-conversation-thread-as-a-turn

/openapi.json post /api/conversations/{route_name}/events
Run a structured event as a turn on an EXISTING thread of ``route_name``.

The thread must already exist: an event enters a conversation as a turn and never mints a
thread. Address it by the ``address`` its listing shows or by its ``thread_id`` (exactly
one). The turn runs the route's TOOL target AS the route's execution key — an
agent-target route is refused (``409``) since an event carries no rendered text. The
event is IDEMPOTENT on ``event_id``: a redelivery returns the original turn's
``message_id`` (``202``) and runs no second turn.

The answer is delivered by the TARGET route's door — a channel route texts the thread's
address, an api route POSTs the route's signed callback (a ``wait_seconds`` body field,
clamped to ``sync_wait_max_seconds``, returns a finished turn's answer inline in the
``200`` and suppresses the callback, but only while the client is still connected — a
hung-up caller's answer falls to the callback or its terminal poll record). Default is
``202 {message_id, thread_id}``.

This is a TRUSTED-integration door: an authorized writer may address ANY existing thread
of the route by ``thread_id`` (a channel participant's included), so a deployment grants its
write action to service principals, not to low-trust API keys.



# Get a conversation route
Source: https://docs.tai42.ai/api-reference/conversations/get-a-conversation-route

/openapi.json get /api/conversations/{route_name}
One conversation route by name, with its ``callback_secret`` withheld.

An unknown name is a loud 404; a name that is not a valid slug is a 400.



# Get a conversation target config
Source: https://docs.tai42.ai/api-reference/conversations/get-a-conversation-target-config

/openapi.json get /api/conversation-configs/{target_kind}/{target_name}
One per-target config by ``(target_kind, target_name)``.

An unknown key is a loud 404; a key whose ``target_kind`` is not a known kind, or whose ``target_name``
is blank, is a 400.



# List a conversation route's threads
Source: https://docs.tai42.ai/api-reference/conversations/list-a-conversation-routes-threads

/openapi.json get /api/conversations/{route_name}/threads
The threads of ``route_name``, newest activity first, one page at a time.

A thread listing spans every caller and address on the route, so it is admin-only. Each
item carries ``thread_id``, ``client_address``, ``message_count``
and ``last_delivery_status`` summarized from the thread's newest readable record, plus
``last_activity_at`` — the route index's own score, which is what this listing SORTS by,
so the moment shown and the position it is shown in always agree. That score is stamped
when a record is created and again when its turn completes; a later delivery transition
on the same record moves the record's ``updated_at`` but not the thread's activity.

``status`` (one of the delivery-status vocabulary) keeps only threads whose summary status
matches; ``address`` keeps only threads whose id client-address suffix contains that
substring. Neither has a direct index — the per-status indexes are GLOBAL over
``message_id``s, not per-route thread ids — so a filter is a BOUNDED app-side post-scan
and a page that spent its scan budget answers ``truncated: true`` LOUDLY, never a silent
cut. An unknown ``status`` is a loud 400.

Authorization is decided BEFORE the route is looked up, so a non-admin is refused the
same way whether the name routes or not — a 404-here/403-there pair would answer which
route names exist to a caller with no business knowing. An unknown route is a loud 404
to an admin; a ``page`` or ``page_size`` below 1, or a ``page`` above the served
maximum, is a 400. Returns
``{"items", "total", "page", "page_size", "next_page", "truncated", "unreadable"}``, where
``total`` counts the route's indexed threads for an unfiltered listing, or the matches the
bounded scan found for a filtered one, and ``unreadable`` counts the threads with no readable
record.



# List conversation routes
Source: https://docs.tai42.ai/api-reference/conversations/list-conversation-routes

/openapi.json get /api/conversations
Every stored conversation route, each with its ``callback_secret`` withheld.

Returns ``{"items", "total", "unreadable"}``, where ``unreadable`` counts the indexed routes
whose row was gone or unparseable.



# List conversation target configs
Source: https://docs.tai42.ai/api-reference/conversations/list-conversation-target-configs

/openapi.json get /api/conversation-configs
Every stored per-target conversation config.

Returns ``{"items", "total", "unreadable"}``, where ``unreadable`` counts the indexed configs
whose row was gone or unparseable.



# List failed conversation deliveries
Source: https://docs.tai42.ai/api-reference/conversations/list-failed-conversation-deliveries

/openapi.json get /api/conversations/messages/failed
List every answer record whose delivery ended ``failed``.

The listing spans every route and caller, so it is admin-only. Returns
``{"items", "total", "unreadable"}``, where ``unreadable`` counts the indexed failed members whose
row was gone or unparseable.



# Read a conversation person
Source: https://docs.tai42.ai/api-reference/conversations/read-a-conversation-person

/openapi.json get /api/conversations/persons/{person_id}
The person row named by ``person_id`` — its identity, folded addresses and stored ``locale``.

``locale`` is the BCP 47 tag the rendering layer resolves text against, or ``null`` when
none is known. The subject read that serves a person's locale. A blank ``person_id`` is a
400; an unknown one a 404; no backend a loud 501.



# Read a conversation thread's control mode
Source: https://docs.tai42.ai/api-reference/conversations/read-a-conversation-threads-control-mode

/openapi.json get /api/conversations/{route_name}/thread/mode
The mode in force for ``thread_id`` on ``route_name`` and where it comes from.

Returns ``{"mode", "source"}``, ``source`` being ``thread`` for a per-thread override and
``route`` for the no-override default. A route-keyed thread's default is the route's
``initial_mode``; a LINKED person's aggregated thread defaults to ``manual`` when ANY
route the person spans defaults to ``manual``, else ``agent``.

The thread-belongs-to-route guard is the thread delete's: a route-keyed id off the route
is a 400, a person thread off the named route a 404. An unknown route is a loud 404; a
blank ``thread_id`` a 400.



# Read a conversation thread's transcript
Source: https://docs.tai42.ai/api-reference/conversations/read-a-conversation-threads-transcript

/openapi.json get /api/conversations/{route_name}/transcript
One thread's records under ``route_name``, one page at a time.

``order`` picks the direction: ``asc`` (the default) reads the transcript oldest first,
``desc`` reads it newest first, which is the order a live tail wants because page 1 then
always holds the latest messages. ``page``/``page_size`` window that order from its own
end, so page 1 of ``desc`` is the newest page and never the oldest.

``q`` filters to records whose inbound text or answer contains that substring — a BOUNDED
scan (the searched text lives inside the record content blob), so a page that spent its
scan budget answers ``truncated: true`` LOUDLY. A ``q`` read never 404s: the unknown-thread
404 below is gated on an UNFILTERED read, so under ``q`` an unknown thread and one that
matched nothing alike read as an EMPTY page.

An admin reads whole records; a non-admin reads the caller-safe projection, which
withholds the internal detail of the route key's run. An unknown ``route_name`` is a loud
404. A thread that is absent or keyed to another route answers the uniform thread
not-found. A ``page`` or ``page_size`` below 1, a ``page`` above the served maximum, a
blank ``thread_id`` or an unknown ``order`` is a 400.

A thread the index still holds but whose rows have expired under the retention TTL is
NOT that 404: it reads as an empty page carrying the indexed ``total``, until the prune
pass reclaims the members and the thread becomes unknown.

Returns ``{"items", "total", "page", "page_size", "next_page", "order", "truncated",
"unreadable", "person_id"}``, where ``total`` counts the thread's indexed records for an
unfiltered read, or the matches a bounded ``q`` scan found, ``unreadable`` counts the members
whose row was gone or unparseable, and ``person_id`` names the linked person of a person
thread (``None`` for a route-keyed thread).



# Read one conversation answer record
Source: https://docs.tai42.ai/api-reference/conversations/read-one-conversation-answer-record

/openapi.json get /api/conversations/{route_name}/messages/{message_id}
One conversation answer record by ``message_id`` under ``route_name``.

A missing record or one on another route is a 404. An admin reads the whole record; a
non-admin reads the caller-safe projection, which withholds the internal detail of the
route key's run.



# Search a conversation route's messages
Source: https://docs.tai42.ai/api-reference/conversations/search-a-conversation-routes-messages

/openapi.json get /api/conversations/{route_name}/messages/search
Return every record on ``route_name`` whose inbound text or answer contains ``q``, one page at a time.

Across ALL the route's threads.
The search spans every caller and address on the route, so it is admin-only, and each item
is the WHOLE record (the same shape the transcript serves an admin). ``q`` is REQUIRED and
non-blank. There is no per-route record index, so the search is a BOUNDED nested scan of
the route's threads and their records; a page that spent its scan budget answers
``truncated: true`` LOUDLY, never a silent cut.

Authorization is decided BEFORE the route is looked up, so a non-admin is refused the same
way whether the name routes or not. An unknown route is a loud 404 to an admin; a blank
``q``, a ``page``/``page_size`` below 1, or a ``page`` above the served maximum, is a 400.
Returns ``{"items", "total", "page", "page_size", "next_page", "truncated", "unreadable"}``,
where ``total`` is the matches the bounded scan found and ``unreadable`` counts the scanned
members whose row was gone or unparseable.



# Send a message to a conversation route
Source: https://docs.tai42.ai/api-reference/conversations/send-a-message-to-a-conversation-route

/openapi.json post /api/conversations/{route_name}/messages
Accept one authed message for ``route_name`` and run its turn AS the route's execution key.

The auth gate authorizes who may SEND; the turn's own authority is the route's
execution key, not the caller. Default answer is ``202 {message_id, thread_id}``; the
answer is then delivered later by signed callback when the route declares a
``callback_url``, and otherwise read back from the poll door
(``GET .../messages/{message_id}``). With a ``wait_seconds`` body field (clamped to
``sync_wait_max_seconds``) a turn finishing in time answers ``200`` inline — an
answered/error turn with the answer, a silent turn with the silent marker (status
``silent``, no answer text) — and any callback (which otherwise carries
answered/error/silent) is suppressed the same way, so it never double-fires; a turn
still running when the wait elapses falls back to ``202``. The inline ``200`` is taken
only while the client is still connected — a caller that hung up during the wait gets its
answer by the route's signed callback (or its terminal poll record), never a write to a
closed socket.



# Send an operator message into a conversation thread
Source: https://docs.tai42.ai/api-reference/conversations/send-an-operator-message-into-a-conversation-thread

/openapi.json post /api/conversations/{route_name}/thread/messages
Send a message BY HAND into ``thread_id`` on ``route_name`` as the route identity.

Returns ``{"message_id", "thread_id"}``. No turn runs: the message is stored already
``answered`` and delivered through the same machine a produced answer takes.

``media`` (a list of ``{"kind", "url", "caption"?, "filename"?}`` display items),
``location`` (a shared map pin ``{"latitude", "longitude", "name"?, "address"?}``),
``template`` (a pre-approved out-of-window template ``{"name", "language", "parameters"?}`` —
``parameters`` is the channel-owned opaque runtime-argument object), ``options`` (a list of
FLAT tappable option objects —
each a ``{"kind": "reply", "text"}`` reply or a ``{"kind": "link", "label", "url"}`` link
action), ``sections`` (the SECTIONED tappable-options alternative — titled groups of reply
rows), ``header``/``footer`` (a media header / trailing line composing an interactive
message) and ``schema`` (an ask-less form's
answer schema — the channel renders ``text`` as the form's prompt, and the participant's
submission enters the conversation as an ordinary inbound message) are OPTIONAL
richer-send forms — FULL parity with the flow answer path's ``AnswerPart`` vocabulary —
delivered ALONGSIDE ``text`` — the message is then stored and delivered as one rich
part, exactly as a produced rich answer is, including the delivery machine's capability
gate (a channel that does not advertise the matching ``supports_*_notifications`` flag
never receives the part; the record fails loudly instead of the field dropping). A
contract-invalid value (an empty list/dict, an over-cap value, or a combination the shared
composition matrix refuses — ``options`` XOR ``sections``, ``schema`` excludes both,
``header``/``footer`` require a choice surface, ``template`` standalone) is a loud 400;
omit them all for a plain text send.

Allowed in either mode and it never flips the mode. Blank ``text`` is a loud 400, and a
present-but-blank ``address`` is a 400. The thread-belongs-to-route guard is the thread
delete's: a route-keyed id must carry the route's ``bridge:{route_name}:`` prefix (400
otherwise), a person thread must be on the named route (404 otherwise). ``address`` picks
the send target on a LINKED person's aggregated thread — it must be one of the person's
addresses (400 otherwise); with no ``address`` the target is the thread's newest record
that is not a send record, and a person thread with no such record and no ``address`` is a
400. For an agent target that holds thread memory the message is appended to the thread's
checkpoint as an ``assistant`` reply BEFORE the record is created; an append that fails is a
loud 500 and no record is created.
The send takes the thread's per-thread FIFO, so it waits behind an in-flight turn and
never interleaves it; a full queue is a loud, retriable 503. As a live-caller sync door the
wait to acquire the slot is bounded by ``sync_door_wait_seconds``: a wait past it — behind a
turn possibly HITL-paused on another worker — is the loud, retriable 503 ``ThreadBusyError``
rather than a block past the proxy timeout.

Caller authority is the door's grantable ``write`` action — the same write grant that
forgets threads — and the record names the calling operator. An unauthenticated caller
(access control disabled or unbound) is a loud 501, since an operator action must be
attributable.



# Set a conversation person's locale
Source: https://docs.tai42.ai/api-reference/conversations/set-a-conversation-persons-locale

/openapi.json put /api/conversations/persons/{person_id}/locale
Set (or clear) a person's stored ``locale``.

The operator override the rendering layer resolves text against, winning over the
channel-seeded value on every later turn. ``locale`` is a BCP 47 tag (canonicalized here —
``he-il`` stores as ``he-IL``); ``null`` clears it back to no-locale-known. A blank
``person_id`` or a malformed ``locale`` is a 400; an unknown person a 404; a person being
erased a 503 with nothing changed; no backend a loud 501. Returns the updated person.



# Set a conversation thread's control mode
Source: https://docs.tai42.ai/api-reference/conversations/set-a-conversation-threads-control-mode

/openapi.json put /api/conversations/{route_name}/thread/mode
Set the per-thread mode override for ``thread_id`` on ``route_name`` to ``mode``.

``mode`` is one of ``agent``/``manual``. Returns ``{"route_name", "thread_id", "mode",
"source"}`` with ``source`` always ``thread`` — a set writes an override.

This is the door an EXTERNAL/programmatic caller names a thread through; an agent flipping
its OWN live conversation uses the ``set_conversation_mode`` builtin instead, which reads
the current thread from the turn context rather than naming it.

Caller authority is the door's grantable ``write`` action. The thread-belongs-to-route
guard is the thread delete's: a route-keyed id off the route is a 400, a person thread off
the named route a 404. An unknown route is a loud 404; a blank ``thread_id`` or a ``mode``
outside the vocabulary is a 400.



# Add or remove single extension combos on a tool
Source: https://docs.tai42.ai/api-reference/extensions/add-or-remove-single-extension-combos-on-a-tool

/openapi.json post /api/tools/{name}/extensions/combos
Granularly edit a tool's extension combos: append ``add`` and drop ``remove``.

Applied over the merge of its current combos, then persisted through the same
pipeline ``set_tool_extensions`` rides. Pinned order (each check loud, nothing
persisted on a reject): the tool must be
REGISTERED (404, as ``get_tool_extensions``); its owning config resolves
(400/400/409, as ``set_tool_extensions``); membership over the OWNING config's
combos in their stored form — adding a present combo → 400, removing an absent
one → 404, each naming the combo; the MERGED list validates against the live
registry (400) before any write. Returns the tool's full new combos in the GET
door's shape.



# Get a tool's applied extension combos
Source: https://docs.tai42.ai/api-reference/extensions/get-a-tools-applied-extension-combos

/openapi.json get /api/tools/{name}/extensions
Return the tool's applied extension combos and the available extensions; 404 for an unknown tool.



# List every registered extension
Source: https://docs.tai42.ai/api-reference/extensions/list-every-registered-extension

/openapi.json get /api/extensions
Return the flat ``{"name", "kind", "multiple"}`` list of every registered extension for the picker.



# Set a tool's applied extension combos
Source: https://docs.tai42.ai/api-reference/extensions/set-a-tools-applied-extension-combos

/openapi.json post /api/tools/{name}/extensions
Author all of a tool's extension combos through the pipeline (persist, reload, broadcast).

Owner resolution, the consolidation-conflict check, and the registry combo
validation all run BEFORE the pipeline (nothing persisted on a reject). The
mutator then upserts the providing config's ``extensions`` entry, and
ConfigService validates the whole document, persists, reloads locally, and
broadcasts the reload so every worker rebinds; the per-worker fleet report rides
the response as its ``fanout`` summary. The persist + local reload have already
landed, so re-running the apply (or a ``reload_config``) is the recovery for a
sibling that did not converge.



# Bind a webhook verifier to a topic
Source: https://docs.tai42.ai/api-reference/hooks/bind-a-webhook-verifier-to-a-topic

/openapi.json put /api/hooks/topics/{topic}/verifier
Bind (or replace) a topic's webhook verifier.

The verifier name is resolved against the registry here — an unknown name is
rejected at BIND time (400), never left to fail at delivery.



# Create a trigger link
Source: https://docs.tai42.ai/api-reference/hooks/create-a-trigger-link

/openapi.json post /api/hooks/trigger-links
Mint a trigger link for ``topic``.

``ttl_seconds`` is the creator's explicit choice (``null`` permanent, positive
timed; ``0``/negative → 400); a unique name is generated when omitted; a
verifier-bound topic is refused (400); ``tool_kwargs`` rides every fire, filling
only the arguments each fired hook's author left
unpinned. ``execution_key`` is the api-key identity the link's dispatch is gated on,
decided BEFORE the mint so a refusal leaves no live URL. ``require_api_key`` makes
the link's door demand an authenticated caller beside the token. Returns
``{"name", "trigger_path", "token", "topic", "expires_at"}``
— the token appears ONLY here (nothing else stores or lists it).

``created_by`` is stamped from the AMBIENT caller identity, never a request field
(which would be caller-spoofable); with the gate off there is no principal and it
is stored ``null``.



# Delete a trigger link
Source: https://docs.tai42.ai/api-reference/hooks/delete-a-trigger-link

/openapi.json delete /api/hooks/trigger-links/{name}
Revoke a trigger link by name — immediate and DURABLE.

A permanent tombstone keeps a restored backup from re-arming it. An unknown name is a
loud 404. Returns ``{"removed", "name"}``.



# Discard a failed hook run
Source: https://docs.tai42.ai/api-reference/hooks/discard-a-failed-hook-run

/openapi.json delete /api/hook-runs/{id}
Delete a failed hook run for good: its hook never runs again for that event.



# List hook runs
Source: https://docs.tai42.ai/api-reference/hooks/list-hook-runs

/openapi.json get /api/hook-runs
Kept hook runs, with the outstanding and failed totals; never their payloads.

``status`` ``outstanding`` lists the pending and running runs, the soonest due first;
``failed`` the failed runs, the most recently failed first; none lists both, outstanding
first. A page holds at most ``limit`` runs; ``cursor`` continues from a page's ``next_cursor``.



# List registered hooks
Source: https://docs.tai42.ai/api-reference/hooks/list-registered-hooks

/openapi.json get /api/hooks
List registered hooks plus the per-topic verifier bindings.

With a topic, lists only the hooks registered for that topic; without one,
lists every registered hook. The response carries the hooks under ``items``
(with ``total``), the per-topic verifier bindings under ``topic_verifiers``, and
under ``trigger_auth`` how a topic's webhook ingress door authenticates its caller —
DERIVED from the live verifier bindings just read, never stored. ``trigger_auth`` is
keyed by every topic among the LISTED hooks plus every topic currently carrying a
verifier binding (one may be bound before any hook exists on it), so under a
``topic`` filter it is neither a subset nor a superset of the listed topics.



# List registered webhook verifiers
Source: https://docs.tai42.ai/api-reference/hooks/list-registered-webhook-verifiers

/openapi.json get /api/hooks/verifiers
The sorted names of every registered webhook verifier — the catalog the Studio bind form offers.

Offered instead of free text. Names ONLY: a verifier object and a bound config are
secret-adjacent and never leave this door. An empty registry (no verifier lifecycle
module loaded) is a valid state, so it returns ``[]``.



# List trigger links
Source: https://docs.tai42.ai/api-reference/hooks/list-trigger-links

/openapi.json get /api/hooks/trigger-links
Every live trigger link's record plus its hash PREFIX and its derived ``trigger_auth``.

Never a raw token (none is stored; a listed link's QR is unrecoverable by design).
Returns ``{"items", "total"}``.



# Register a hook
Source: https://docs.tai42.ai/api-reference/hooks/register-a-hook

/openapi.json post /api/hooks
Register a hook from its flat parameters — an UPSERT (the create path and the edit path).

Supports conditional execution (``condition``) and the four door-contract expressions
(``start_expr`` builds the fired tool's kwargs; ``cancel_expr`` / ``resume_expr`` act on the
run's parked interactions; ``extras_expr`` builds the started run's extras) — each a templated
text carrying its jq inline or by stored id — plus dynamic tool arguments.
``execution_key`` is the api-key identity every fire runs as; the caller's authority
to delegate it and its usability by a tokenless fire are decided BEFORE the upsert, so
a refusal stores nothing and leaves any existing hook of that name untouched. Returns
``{"registered", "name"}``; ``registered`` is ``True`` for a create and a replace
alike.



# Retry a failed hook run
Source: https://docs.tai42.ai/api-reference/hooks/retry-a-failed-hook-run

/openapi.json post /api/hook-runs/{id}/retry
Re-queue a failed hook run as a fresh run with the same id, and so the same idempotency key.

A run whose hook started its tool replays that start alone; any other runs its hook again on
the current parked entries. A run whose hook committed a resume or a take is refused: retrying
it would act twice, so it can only be discarded. Answers the re-queued run.



# Unbind a topic's webhook verifier
Source: https://docs.tai42.ai/api-reference/hooks/unbind-a-topics-webhook-verifier

/openapi.json delete /api/hooks/topics/{topic}/verifier
Remove a topic's verifier binding, reopening its public ingress door.

A missing binding is a loud 404.



# Unregister a hook
Source: https://docs.tai42.ai/api-reference/hooks/unregister-a-hook

/openapi.json delete /api/hooks/{name}
Unregister a hook by name. An unknown hook name is a loud 404.

Returns ``{"removed", "name"}``.



# Answer a pending interaction
Source: https://docs.tai42.ai/api-reference/interactions/answer-a-pending-interaction

/openapi.json post /api/interactions/{interaction_id}/answer
Answer a pending interaction through the authenticated human door.

Audience gate (after the existence/format/status guards): a question's
``audience`` identity OR any unrestricted caller (the operator can always unblock
a stuck question) may answer; every OTHER restricted caller is a loud ``403``.
An unaddressed question is answerable by any unrestricted caller and by no
restricted caller. This gate is sound ONLY because a restricted caller can never
obtain a question's callback ticket — the ticket is delivered exclusively over the
configured channel (never on any read/stream frame), so the unauthenticated
callback door stays the sole ticket-bearing surface and no filtered stream leaks
it.



# Cancel a pending interaction
Source: https://docs.tai42.ai/api-reference/interactions/cancel-a-pending-interaction

/openapi.json post /api/interactions/{interaction_id}/cancel
Cancel a pending interaction — WITHDRAW one specific ask without answering or deleting its thread.

The mirror of ``answer_interaction`` for the terminal-without-an-answer case: it
takes the pending question's whole run down through the status-gated kill seam
(``kill_park``) — every open ask of the run, nested runs and the callers waiting on it —
so NO continuation fires — nothing of the run is resumed — and the removed event
rides tagged ``reason="cancelled"`` so a live operator surface tells a deliberate
withdrawal apart from a timeout/expiry removal. A door that started the run is delivered
the ``withdrawn`` terminal: nothing is said to the person.

Status-gated exactly like the answer door: only a PENDING (or parked) question cancels.
A question already ``answered`` (its state retained) is a loud ``409`` conflict; a
question whose state is GONE — expired, already cancelled, or never existed (all
leave no distinguishable tombstone, the same limit the answer door has) — is a ``404``.
Idempotent at the store seam: the teardown re-run on a withdrawn question is a
clean no-op, so a re-cancel simply reports the question gone (``404``) rather than
double-tearing anything down. It is a TEARDOWN door, so unlike the user-facing answer
door it accepts a CALLER ask (``to="caller"``) as well as a user ask, and unlike the
answer door it is answer-format-AGNOSTIC: an EXTERNAL ask is a pending ask an operator
may withdraw, so it is cancellable too.

The teardown withdraws the channel delivery through the delivering channel's ``withdraw``
member, so the channel's hold on the person's address is released and that address is free
for the next ask when this door returns; the rest of the run's takedown is durable and
finishes behind the door. The question already sent stays on the medium: a
participant who still answers it reaches the callback door, finds the state gone and gets a
``404``, which the inbound ladder maps to a fresh bridged turn.

Audience gate identical to ``answer_interaction`` (after the existence/status guards):
a question's ``audience`` identity OR any unrestricted caller (the operator can always
withdraw a stuck question) may cancel; every other restricted caller is a loud ``403``.



# External interaction callback door
Source: https://docs.tai42.ai/api-reference/interactions/external-interaction-callback-door

/openapi.json get /api/interactions/callback/{ticket}
Serve the external interaction callback door (GET page, POST answer claim).



# External interaction callback door
Source: https://docs.tai42.ai/api-reference/interactions/external-interaction-callback-door-1

/openapi.json post /api/interactions/callback/{ticket}
Serve the external interaction callback door (GET page, POST answer claim).



# External interaction mid-form reaction door
Source: https://docs.tai42.ai/api-reference/interactions/external-interaction-mid-form-reaction-door

/openapi.json post /api/interactions/callback/{ticket}/react
Serve the unauthenticated mid-form reaction door (POST only), under the ticket capability.



# List parked (async) interactions awaiting an answer
Source: https://docs.tai42.ai/api-reference/interactions/list-parked-async-interactions-awaiting-an-answer

/openapi.json get /api/interactions/pending
A read-only admin audit of the parked async asks awaiting an answer.

The native surface a scheduled watchdog flow reads to spot parks nearing (or past) their
expiry.

An UNRESTRICTED operator sees the whole cross-audience set — exactly the reach the
operator inbox (``list_interactions``) already grants. A RESTRICTED caller sees ONLY
the parks addressed to its identity, the same audience filter the inbox applies —
never a 403: this operation is projected, and a projected route must agree with the
gate for every identity it is projected to (the owned-keys e2e pins that invariant).
Reads the ``pending:expiry`` index WITHOUT mutating it (no claim, no TTL change):
purely an audit. ``limit`` is clamped to ``1..``:data:`MAX_PENDING_INTERACTIONS_LIMIT`
(default :data:`DEFAULT_PENDING_INTERACTIONS_LIMIT`); it bounds the underlying index
scan, so a restricted caller's filtered slice may hold fewer items. Returns
``{"items", "count"}`` — each item carries ``interaction_id``, ``group_id``,
``question`` (truncated), ``channel``, ``recipient``, ``audience``, ``thread_id``
(when the park carries one), ``expiry_at``, ``created_at``, ``mode``.



# List pending interactions
Source: https://docs.tai42.ai/api-reference/interactions/list-pending-interactions

/openapi.json get /api/interactions
The pending questions the inbox shows, one page at a time.

The initial-load surface a client reads BEFORE applying the live stream
(``GET /api/interactions/stream``).

Order is the store's pending order (each group's most-recent question ``created_at``,
then stream order within a group). A RESTRICTED caller sees ONLY questions addressed
to its identity — the audience filter runs BEFORE paging so ``total`` is honest; an
UNRESTRICTED caller sees every pending question. A ``page`` or ``page_size`` below 1,
or a ``page`` above the served maximum, is a 400; a ``page_size`` above the cap is
capped, never refused. The pending read reconciles phantom/abandoned questions as it
goes (phantom-group prune, abandoned past-deadline prune, answered/missing skip). Returns
``{"items", "total", "page", "page_size", "next_page", "truncated"}`` — ``items``
carry the same shape as the stream's add frames, and ``truncated`` is always
``false`` (the pending index is the whole set, sliced in memory).



# React to an open form interaction
Source: https://docs.tai42.ai/api-reference/interactions/react-to-an-open-form-interaction

/openapi.json post /api/interactions/{interaction_id}/react
React to an OPEN reacting form through the AUTHENTICATED in-app door — the ``channel=None`` surface.

The SIBLING of the authenticated answer door, under the SAME authenticated correlation:
the same existence/format/status guards and the SAME audience gate (a restricted caller
may react only to a form addressed to its identity). It then runs the ONE ``react``
chokepoint, which asserts the form is open, type-validates the partial values, runs the
asker's handler under its stored identity with a deadline, validates the returned update,
and returns it. STATELESS: no answer is recorded, the interaction is never resolved, the
stored request is never rewritten. A closed form is a ``409``, a malformed request a
``400``, and a handler that raises or times out a loud ``502`` (never a stale value).



# Serve interaction media stored by reference
Source: https://docs.tai42.ai/api-reference/interactions/serve-interaction-media-stored-by-reference

/openapi.json get /api/interactions/media/{media_id}
Serve stored interaction media by its id: 400 malformed id, 404 miss, 503 blob provider gone.



# Serve interaction media stored by reference
Source: https://docs.tai42.ai/api-reference/interactions/serve-interaction-media-stored-by-reference-1

/openapi.json head /api/interactions/media/{media_id}
Serve stored interaction media by its id: 400 malformed id, 404 miss, 503 blob provider gone.



# Stream the interactions inbox live tail
Source: https://docs.tai42.ai/api-reference/interactions/stream-the-interactions-inbox-live-tail

/openapi.json get /api/interactions/stream
Serve the interactions inbox live tail as an SSE ``StreamingResponse``.

Refuses with a plain 501 when the store is unconfigured; otherwise resumes from the
caller's ``Last-Event-ID`` (or the current tail end) and streams the live tail.



# Exchange a one-time claim token for its API key
Source: https://docs.tai42.ai/api-reference/login/exchange-a-one-time-claim-token-for-its-api-key

/openapi.json post /api/login/claim
Burn a one-time claim token and return the raw API key it carried — the public exchange leg.

The public exchange leg of QR onboarding: its route is public by declaration
(``authed=False``) and a pre-authentication surface (``pre_auth=True``), so a presented
credential is never verified.

The claim record is single-use: a used / unknown / expired token all answer the SAME
404 (no oracle distinguishing them). The handed-out key is guaranteed not-REVOKED
(re-validated at exchange), NOT owner-alive — owner-death is enforced by the gate on
every request. Response mirrors the ``loginResult`` wire shape:
``{"data": {"token": <raw key>, "user_id": ...}}``.

``authority_changing=True`` keeps this OFF the default MCP tool surface: a
credential-exchange login door is not an agent tool (it sits outside the
``/api/auth/*`` prefix, so the flag is what excludes it, not the prefix).



# List available login methods
Source: https://docs.tai42.ai/api-reference/login/list-available-login-methods

/openapi.json get /api/login/methods
Aggregate every registered accounts provider's login methods + the setup state.

Its route is public by declaration (``authed=False``) and a pre-authentication surface
(``pre_auth=True``): it is served without a credential, and a presented credential is
never verified, so a stale one cannot lock a caller out of login. Each method is
serialized with ``model_dump(exclude_none=True)`` so a ``None``-valued optional
(icon/autocomplete) is OMITTED, never ``null`` (the Studio's zod schemas accept absent but reject
``null``). ``needs_setup`` is the one platform fact "no principal exists"; ``setup_login``
names what the setup door can attach (``kinds`` from a configured login-attaching
provider, ``null`` when none); ``claim_fragment_key`` the declared claim-link fragment key.
Provider errors propagate (loud, never a silently empty
methods list).



# Add or replace agents config entries and hot-reload
Source: https://docs.tai42.ai/api-reference/manifest/add-or-replace-agents-config-entries-and-hot-reload

/openapi.json post /api/agents-config/entries
Add ``entries`` to the manifest's ``agents`` section (``replace`` swaps colliding titles) and reload.



# Add or replace MCP config entries and hot-reload
Source: https://docs.tai42.ai/api-reference/manifest/add-or-replace-mcp-config-entries-and-hot-reload

/openapi.json post /api/mcp-config/entries
Add ``entries`` to the manifest's ``mcp`` section (``replace`` swaps colliding titles) and reload.



# Add or replace tools config entries and hot-reload
Source: https://docs.tai42.ai/api-reference/manifest/add-or-replace-tools-config-entries-and-hot-reload

/openapi.json post /api/tools-config/entries
Add ``entries`` to the manifest's ``tools`` section (``replace`` swaps colliding titles) and reload.



# Add/remove names on the api_tools include/exclude lists and hot-reload
Source: https://docs.tai42.ai/api-reference/manifest/addremove-names-on-the-api_tools-includeexclude-lists-and-hot-reload

/openapi.json post /api/api-tools
Add/remove names on the ``api_tools`` include/exclude lists and hot-reload the manifest.

Returns the apply response. An empty change, a duplicate add, or a missing remove is a
loud 400/404.



# Detach a single MCP server's tools by title
Source: https://docs.tai42.ai/api-reference/manifest/detach-a-single-mcp-servers-tools-by-title

/openapi.json post /api/mcp-status/{title}/deregister
Detach a single MCP server's tools (by manifest title) without touching the other servers.

The removal counterpart of ``reload_mcp``. Applied on this worker through the gate and
broadcast to the fleet (all workers, or only ``targets``); the response embeds the per-worker
fleet report.



# Get the JSON schema for one MCP-config entry
Source: https://docs.tai42.ai/api-reference/manifest/get-the-json-schema-for-one-mcp-config-entry

/openapi.json get /api/mcp-config/schema
The JSON schema for one MCP-config entry.



# List MCP servers skipped by the viability check
Source: https://docs.tai42.ai/api-reference/manifest/list-mcp-servers-skipped-by-the-viability-check

/openapi.json get /api/mcp-status/failed
List MCP servers skipped due to a failed viability check (server down or slow).

Skipped at boot or last reload. Use ``reload_mcp`` to re-attach one once healthy.

Each entry is ``{"title", "status", "category", "message", "http_status"}`` — the
title plus the coarse status and a credential-free failure detail (``category`` one
of ``auth`` / ``unreachable`` / ``error``, the redacted ``message``, and the
``http_status`` when the failure carried one). A query op rides the same fan-out primitive as a mutation:
every worker's list arrives as its per-worker ``payload`` in the fleet report
(this worker's list on its own self entry); ``targets`` optionally restricts the
query to specific workers.



# List the manifest MCP section's !ENV marker refs (names + set/unset only)
Source: https://docs.tai42.ai/api-reference/manifest/list-the-manifest-mcp-sections-!env-marker-refs-names-+-setunset-only

/openapi.json get /api/manifest/mcp-env-refs
The ``!ENV ${VAR[:default]}`` markers carried by the manifest's MCP section.

NAMES and BOOLEANS only, never values.

Walks the PRESERVED manifest (markers intact) with the shared marker scan and
returns one row per marker ref, in document order:
``{var, pointer, has_default, set}``. ``pointer`` is the RFC 6901 json-pointer of
the leaf (``/mcp/<i>/config/...``); ``has_default`` is whether the ref carries a
``:default``; ``set`` is whether the var is present in ``os.environ`` — the SAME
effective env the store flows into and the source-marker resolution + dangling
refusals read, so a var supplied only by the deployment environment shows green,
never a false red. Works identically for hand-written marker-bearing entries (a
platform feature, not an mcp-server-kind feature).



# Re-probe every failed MCP server
Source: https://docs.tai42.ai/api-reference/manifest/re-probe-every-failed-mcp-server

/openapi.json post /api/mcp-status/reload-failed
Re-probe every MCP server currently in the failed list and attach the ones now viable.

Applied on this worker through the gate and broadcast to the fleet (all workers, or only
``targets``); the response embeds the per-worker fleet report.



# Read the PRESERVED manifest (markers intact) MCP section and user tools
Source: https://docs.tai42.ai/api-reference/manifest/read-the-preserved-manifest-markers-intact-mcp-section-and-user-tools

/openapi.json get /api/manifest/preserved
Return the PRESERVED persisted manifest's MCP section + user tools, every ``!ENV`` marker intact.

No secret is resolved — the source the Studio McpTab config editor reads so it can round-trip
markers instead of baking a resolved secret. Same ``{mcp, user_tools}`` view as
``get_manifest`` — both serve the preserved read; this explicit ``/preserved`` door names that
no-resolve contract in its path.



# Read the PRESERVED manifest MCP section and user tools
Source: https://docs.tai42.ai/api-reference/manifest/read-the-preserved-manifest-mcp-section-and-user-tools

/openapi.json get /api/manifest
Return the MCP section and user tools of the PRESERVED persisted manifest.

``!ENV ${KEY}`` markers are kept intact, so a secret leaf is its placeholder marker, NEVER the
plaintext value.

This door serves ONLY the preserved read: no resolved-view surface exists here, so no
``!ENV`` marker is ever materialized onto the wire. McpTab reads
``/api/manifest/preserved`` and ManifestTab renders the markers directly.



# Reload a single MCP server by title
Source: https://docs.tai42.ai/api-reference/manifest/reload-a-single-mcp-server-by-title

/openapi.json post /api/mcp-status/{title}/reload
Re-probe a single MCP server by ``title`` (unknown title → loud 404) and reattach it.

Applied on this worker through the gate and broadcast to the fleet (all workers, or only
``targets``); the response embeds the per-worker fleet report. If the local re-probe raises,
nothing is broadcast.



# Remove one agents config entry by title and hot-reload
Source: https://docs.tai42.ai/api-reference/manifest/remove-one-agents-config-entry-by-title-and-hot-reload

/openapi.json delete /api/agents-config/entries/{title}
Remove the ``agents`` entry named ``title`` and hot-reload; an unknown title is a 404.



# Remove one MCP config entry by title and hot-reload
Source: https://docs.tai42.ai/api-reference/manifest/remove-one-mcp-config-entry-by-title-and-hot-reload

/openapi.json delete /api/mcp-config/entries/{title}
Remove the ``mcp`` entry named ``title`` and hot-reload; an unknown title is a 404.



# Remove one tools config entry by title and hot-reload
Source: https://docs.tai42.ai/api-reference/manifest/remove-one-tools-config-entry-by-title-and-hot-reload

/openapi.json delete /api/tools-config/entries/{title}
Remove the ``tools`` entry named ``title`` and hot-reload; an unknown title is a 404.



# Replace the MCP config section and hot-reload
Source: https://docs.tai42.ai/api-reference/manifest/replace-the-mcp-config-section-and-hot-reload

/openapi.json post /api/mcp-config
Replace the manifest's ``mcp`` section through the pipeline and hot-reload the fleet.

The mutator edits the PRESERVED document in place, then ConfigService validates, persists,
reloads locally, and broadcasts the reload to the whole fleet. A malformed entry fails
validation inside the transaction (nothing persisted) and maps to a loud 400.



# Replace the whole manifest, persist, and reload the fleet
Source: https://docs.tai42.ai/api-reference/manifest/replace-the-whole-manifest-persist-and-reload-the-fleet

/openapi.json post /api/manifest/replace
Replace the WHOLE manifest fleet-wide and persist it.

The posted ``manifest_text`` is the PRESERVED view (``!ENV`` markers intact); the
server loads it to the preserved document and pushes it through the pipeline —
validate the RESOLVED projection, persist verbatim (no secret bakes to disk),
reload locally, and broadcast the reload so every worker re-reads the persisted
store. The response embeds the per-worker fleet report as its ``fanout`` summary.
A persisted replacement reaches the whole fleet, so there is no ``targets``.

Authority-changing — the manifest governs ``api_tools`` + module loading — so it
is off the default MCP surface (tier 2), projectable via an explicit
``api_tools.include``.



# Snapshot the live MCP binding status
Source: https://docs.tai42.ai/api-reference/manifest/snapshot-the-live-mcp-binding-status

/openapi.json get /api/mcp-status
A snapshot of the live MCP binding status.



# Write a secret env value and its manifest !ENV marker together, then reload
Source: https://docs.tai42.ai/api-reference/manifest/write-a-secret-env-value-and-its-manifest-!env-marker-together-then-reload

/openapi.json post /api/mcp-config/secret-env
Store a pasted secret as an env value and reference it from the manifest by a marker.

The env KEY is EITHER an explicit ``key`` OR generated from ``key_hint`` — exactly one
(``key | key_hint``). Writes the secret ``value`` to the env store under that key AND
marks the key secret (adding it to ``TAI_ENV_SECRET_KEYS``), and writes an ``!ENV ${KEY}``
MARKER at ``manifest_pointer`` — all through the combined
``ConfigService.apply_env_and_change`` pipeline so the env write and the manifest mutate
stay consistent. Partial-failure: a manifest-persist failure after the env write does
NO rollback — the env write stands as an inert, re-runnable orphan and the op raises
loudly. An explicit ``key`` colliding with an existing stored key holding a DIFFERENT value
is a loud 400 naming the key; a generated key never shadows a registered settings
``env_var``. The pointer's HEAD segment MUST be ``mcp`` (loud 400 otherwise). The response
is the ``reloadConfigResult`` shape; the resolved key is NEVER returned. A dangling
``!ENV`` / X-band refusal surfaces as a loud 400 naming the key (the shared boundary
validator, same as ``POST /api/mcp-config``). An explicit ``key`` that is a recycle-class
setting rolls a worker recycle as every env write does (the response's ``recycle``; this
worker recycles itself after replying when the roll converged).



# Get a marketplace listing's detail
Source: https://docs.tai42.ai/api-reference/marketplace/get-a-marketplace-listings-detail

/openapi.json get /api/marketplace/plugins/{ns}/{name}
One listing's detail composed with its version rows in a single body.

So the detail view (listing + the Versions card) is one request. The registry's
display metadata (``display_name``/``homepage_url``/``license``/``readme_md``)
survives the spread.



# Get advisories for installed plugins
Source: https://docs.tai42.ai/api-reference/marketplace/get-advisories-for-installed-plugins

/openapi.json get /api/marketplace/advisories
The advisory snapshot for the installed plugins, no older than the configured poll interval.

A stale snapshot is refreshed on demand, and a refresh failure raises a loud 502
rather than serving stale data.



# Install a marketplace plugin
Source: https://docs.tai42.ai/api-reference/marketplace/install-a-marketplace-plugin

/openapi.json post /api/marketplace/install
Resolve, pip install, patch the manifest, reload, and record attribution.

Nothing is pip-installed for a descriptor-only plugin; aborts and unwinds on any
failure (see :meth:`Installer.install`). When the spec declares install-time env
``env`` / ``secret_keys`` satisfy the required ``!ENV`` markers or connector-env in
the same combined transaction. ``route_mounts`` remaps declared route bases;
``accept_public_routes`` acknowledges public routes. The result's ``routes`` lists
every route the install mounted. An install-time env change carrying a recycle-class key
rolls a worker recycle (the receipt's ``reload.recycle``); when it converged this worker
recycles itself after replying.



# List installed marketplace plugins
Source: https://docs.tai42.ai/api-reference/marketplace/list-installed-marketplace-plugins

/openapi.json get /api/marketplace/installed
The installed inventory.

Shaped ``{"installed": [...]}``.

Each installed row carries the update picture computed from the registry's
version rows against the RUNNING contract: ``latest`` (newest published
version, or ``null`` with none), ``update_available`` (a newer COMPATIBLE
version exists — an incompatible newer version never advertises as an
update), ``incompatible_newer`` (the newest such blocked version, so "an
update exists but needs a newer core" is visible, or ``null``), and
``compat`` — the live ``{status, reason}`` verdict of the row's installed
distribution against the running contract. A per-row not-found — the
upstream listing vanished or was suspended — is row STATE, not a route
failure: that row answers ``latest: null``, ``update_available: false``,
``missing_upstream: true``, so one dead listing never fails the whole
inventory. A transport/garbled-upstream failure still surfaces as a 502,
and a garbled LOCAL row (a stored spec that no longer validates, a malformed
stored ref, an unparsable stored version) as a 500 naming the row — serving
rows without their update picture would be a silent degrade of the spec'd
shape.

Each row also carries ``items`` — the ``{kind, name}`` of every item its
stored spec provides (from LOCAL truth, never the registry). Studio joins
these against the manifest's ``mcp`` entry titles to render an
installer-written entry read-only.

Each row also carries ``route_mounts`` — the persisted ``{item_name: base}``
mount the row is installed at (empty means every item at its declared base),
so Studio seeds its update flow and renders routes at the ACTUAL mounted base.

Each row also carries ``delivery`` — ``package`` for a pip-installed plugin,
``descriptor`` for a descriptor-only plugin whose stored spec names no package.



# List marketplace categories
Source: https://docs.tai42.ai/api-reference/marketplace/list-marketplace-categories

/openapi.json get /api/marketplace/categories
The registry's controlled category vocabulary — a plain array Studio renders as facet chips.



# List marketplace item kinds
Source: https://docs.tai42.ai/api-reference/marketplace/list-marketplace-item-kinds

/openapi.json get /api/marketplace/kinds
The registry's controlled item-kind vocabulary — a plain array Studio renders as facet chips.



# Preview a marketplace install
Source: https://docs.tai42.ai/api-reference/marketplace/preview-a-marketplace-install

/openapi.json post /api/marketplace/install/preview
Resolve a candidate install/update and report its routes WITHOUT changing any state.

The resolved routes per item with ``route_mounts`` overrides applied, the
collisions against the live registry (excluding the plugin's own routes on an
update preview), the public routes requiring acceptance, and the ``new`` public
rows an update has not already approved (see :meth:`Installer.preview`).



# Search the marketplace
Source: https://docs.tai42.ai/api-reference/marketplace/search-the-marketplace

/openapi.json get /api/marketplace/search
Proxy the registry's public search, forwarding the whitelisted facets.

``tags`` is multi-value end to end (the registry receives repeated ``tags``
params); every other facet is single-valued. ``None`` facets are dropped. The
registry's rows ride through unchanged, so display metadata (``display_name``,
``icon_url``) is transparently forwarded.



# Uninstall a marketplace plugin
Source: https://docs.tai42.ai/api-reference/marketplace/uninstall-a-marketplace-plugin

/openapi.json post /api/marketplace/uninstall
Unpatch the manifest, reload, pip uninstall, and drop attribution.

Convergent and registry-free (see :meth:`Installer.uninstall`).



# Update a marketplace plugin
Source: https://docs.tai42.ai/api-reference/marketplace/update-a-marketplace-plugin

/openapi.json post /api/marketplace/update
Resolve the target, pip upgrade, re-patch the manifest, reload, and upsert attribution.

Nothing is pip-upgraded for a descriptor-only plugin; the same pre-flights apply
as install (see :meth:`Installer.update`). ``env`` / ``secret_keys`` satisfy a new
version's required ``!ENV`` markers or connector-env. ``route_mounts`` remaps
declared route bases (surviving items keep their stored base);
``accept_public_routes`` acknowledges public routes not already approved. The
result's ``routes`` lists every route the update mounted. An update-time env change
carrying a recycle-class key rolls a worker recycle (the receipt's ``reload.recycle``);
when it converged this worker recycles itself after replying.



# Upgrade all installed marketplace plugins
Source: https://docs.tai42.ai/api-reference/marketplace/upgrade-all-installed-marketplace-plugins

/openapi.json post /api/marketplace/upgrade-all
Move every installed plugin onto its latest COMPATIBLE version in one lock-held batch.

Answers ``{"results": [{ref, outcome, detail}, ...]}``.

Per-ref failures (including a ref with NO compatible version) are report
entries, never a batch abort — the ONE operation-level failure is the
fleet marketplace lock being held elsewhere (the retriable 503). See
:meth:`Installer.upgrade_all` for the outcome vocabulary.



# List internal notifications
Source: https://docs.tai42.ai/api-reference/notifications/list-internal-notifications

/openapi.json get /api/notifications
List internal notifications, newest-first.

A RESTRICTED caller reads its OWN per-identity feed (complete within its own
bound — never truncated by other identities' volume, never a broadcast); an
UNRESTRICTED caller reads the shared feed unchanged (the operator view).



# Send a human a one-way notification
Source: https://docs.tai42.ai/api-reference/notifications/send-a-human-a-one-way-notification

/openapi.json post /api/notifications
Send a human a one-way notification, fire-and-forget.

No reply is expected and nothing blocks. With a named channel the message is
sent and the call returns as soon as the medium ACCEPTED it (not that a human
saw it). With ``channel`` omitted the message is recorded to the internal
notifications sink the Studio inbox reads. One send attempt, no retry; every
failure raises loudly, never a silent no-op:

* a blank message with no media to carry it (the contract admits a blank message
  only for a media-only send), an unknown channel name, a blank recipient/audience, a
  caller-supplied ``sender_identity``, a contract-invalid ``media``/``template``/
  ``options``/``schema`` combination (an empty list/dict, an over-cap value, or a
  mutually exclusive
  media+template / options+template / schema+template / schema+options), a ``schema``
  with no channel (the internal sink has no submission door) or one the channel's form
  subset/hook refuses, or a channel's permanent refusal of the input's
  shape (retrying cannot succeed) → 400;
* a restricted caller addressing another identity (cross-identity denial) → 403;
* a channel that cannot notify, or does not advertise the
  ``media``/``template``/``options``/``schema`` capability the send needs → 501;
* a transient channel delivery failure (the raised error's ``retryable``) → 503,
  carrying the medium's ``retry_after`` when it named one;
* a permanent channel delivery refusal → 502.

``media`` (display media sent with the message), ``location`` (a shared map pin),
``template`` (a pre-approved out-of-window send), ``options`` (FLAT tappable options a tap
of which enters the conversation), ``sections`` (the SECTIONED tappable-options
alternative), ``header``/``footer`` (a media header / trailing line composing an interactive
message) and ``schema`` (an ask-less form's answer schema — the channel renders the
message as the form's prompt, and a submission enters the conversation as a message from
the person) are OPTIONAL richer-send forms — FULL parity with the flow answer path's
``AnswerPart`` vocabulary. The contract's shared composition matrix is enforced on this
request model identically: ``options`` XOR ``sections`` (one choice surface); ``schema``
excludes both; ``header``/``footer`` require a choice surface; ``template`` is the standalone
out-of-window send exclusive with every other content/interactive field; ``options``/
``sections`` may each combine with ``media``/``location`` (a contract-invalid combination is
a 400). On a
named channel each needs a channel that advertises the matching capability
(``media``→media, ``location``→location, ``template``→template, ``options``/``sections``→
interactive, ``schema``→form; ``header``/``footer`` ride the choice surface's capability, no
flag of their own) — otherwise
the send is refused as a 501, never downgraded to a silent freeform send. With no
channel media/location/template/options/sections/header/footer are stored on the internal
inbox record and rendered
there; ``schema`` alone REQUIRES a channel (a 400 without one) — a stored form nobody
could submit would be a dead surface, not a notification.

``data`` (per-send prefill ``values`` and per-send ``options`` lists) and ``pages`` (the
stepped layout) are the ask-less form's per-send extras — the same ``FormData``/``FormPage``
an ask carries. They ride ONLY a form send: present without ``schema`` is a 400. When a
``schema`` is present each is cross-checked against it by the same validator the ask door
runs — a prefill against an unknown/ill-typed property, a per-send option list on a
non-string property, or a page that omits/duplicates/misnames a property is a 400.

``form_tag`` is the caller-set opaque per-send correlation the channel carries with the form
and hands back on submit. It rides ONLY a form send: present without ``schema`` is a 400. The
platform bounds it (an out-of-charset or over-length tag is a 400) but never interprets it,
and it is not written to the in-app feed record.

``wording`` is the per-send catalogue of the notification's platform-drawn texts, grouped by
what each decorates — ``form`` (a form send's chrome), ``choice`` (a choice list's control
words) and ``status`` (in-flight status copy). Each member is admitted only on the surface that
draws it (a ``schema`` form, a flat ``options`` list, or a sectioned ``sections`` list); a
member on a notification with no such surface is a 400. It is display content, so an
``audience``-addressed send records it on the in-app feed.

``audience`` addresses the in-app record to an identity's feed; it is honored
even when a channel also delivers the message (channel push AND in-app record).
``sender_identity`` is the sending identity a channel message leaves FROM, which the
conversation bridge sets on the notification it builds to answer a route; a caller may
not supply it here and a set value is rejected loudly, never forwarded to the channel.

Returns a short confirmation string — ``"notification sent via '<channel>'"``
for a channel send, ``"notification recorded to the internal sink"`` otherwise.



# Export a run's trace as a JSON download
Source: https://docs.tai42.ai/api-reference/observability/export-a-runs-trace-as-a-json-download

/openapi.json get /api/observability/runs/{trace_id}/trace/export
Single run's full trace as a downloadable JSON file; ``resolve=true`` resolves every span's references first.



# Export runs as a CSV download
Source: https://docs.tai42.ai/api-reference/observability/export-runs-as-a-csv-download

/openapi.json get /api/observability/runs/export
Bulk export of the filtered run list as CSV (default) or JSON.

Honors the same advanced filters as the run list. Capped at ``_EXPORT_CAP`` rows;
truncation is flagged in-band (never a silent loss).



# Get a run span's resolved value
Source: https://docs.tai42.ai/api-reference/observability/get-a-run-spans-resolved-value

/openapi.json get /api/observability/runs/{trace_id}/spans/{span_id}/resolved
One span field's value at ``pointer``, with every record reference on the way and inside it resolved.

The pointer is applied exactly as a reference's pointer: a step that lands on a
reference resolves it and continues inside its value. An absent trace or span is a 404;
a reference the backend does not hold (not yet ingested, or lost), or a pointer the
record does not hold, is a 502 carrying the reason.



# Get a run's trace
Source: https://docs.tai42.ai/api-reference/observability/get-a-runs-trace

/openapi.json get /api/observability/runs/{trace_id}/trace
Full detailed trace for one run via the contract's ``get_trace``.

The contract's ``get_trace`` always returns a trace or raises: an absent trace
is ``TraceNotFoundError`` → 404, and every other backend error propagates as a
loud 500.



# Get a run's trace outline
Source: https://docs.tai42.ai/api-reference/observability/get-a-runs-trace-outline

/openapi.json get /api/observability/runs/{trace_id}/trace/outline
The span tree of one run via the contract's ``get_trace``: every span without its input and output.

An absent trace is a 404 and a read the backend cannot serve a 501, exactly as ``get_run_trace``.



# Get the monitoring backend's observability capabilities
Source: https://docs.tai42.ai/api-reference/observability/get-the-monitoring-backends-observability-capabilities

/openapi.json get /api/observability/capabilities
The run-list page ceiling, sorts and sort/filter incompatibilities, and the metrics measures and dimensions.

Read from the backend's pure declarations (``max_page_size``, ``list_capability``,
``metrics_capability``) in the run list's wire names; no backend query is issued.



# List observability runs
Source: https://docs.tai42.ai/api-reference/observability/list-observability-runs

/openapi.json get /api/observability/runs
Filterable run list via the contract's ``list_traces``, paged with the reader's ``limit`` / ``page``.

Time range plus the neutral advanced filters (tags / status / cost / token / latency
ranges) and sort. ``page_size`` is capped to the backend's declared ``max_page_size``.

List- or dict-typed query params are JSON-encoded in the query string
(``tags`` may be a JSON list ``["a","b"]`` or a comma-separated string).



# Query observability metrics
Source: https://docs.tai42.ai/api-reference/observability/query-observability-metrics

/openapi.json get /api/observability/metrics
Aggregate metrics over the time range via the contract's ``query_metrics``.

The backend DECLARES what it serves (``metrics_capability``) before any query.
A backend that does not serve the core measures fails loudly (501). The by-model
panel's availability is the backend's DECLARATION that it groups by the model
dimension — not a swallowed query error: when declared, the by-model query runs
HARD and any failure propagates; when not declared, the panel is reported absent
and no query is issued.



# List the registered studio plugins
Source: https://docs.tai42.ai/api-reference/plugins/list-the-registered-studio-plugins

/openapi.json get /api/plugins
Every registered studio plugin's manifest contents and route mounts, or a loud 500 if the registry is unbuilt.

``mounts`` is read off the committed route generation, so a remapped or dropped route item reads as it is
served now.



# Serve a studio plugin asset
Source: https://docs.tai42.ai/api-reference/plugins/serve-a-studio-plugin-asset

/openapi.json get /api/plugins/{name}/studio/{path}
Serve an integrity-pinned static asset for a studio plugin, or a 404/500 error response.



# Create a preset
Source: https://docs.tai42.ai/api-reference/presets/create-a-preset

/openapi.json post /api/presets
Create a preset, atomically.

The shared :func:`_create_preset_core` runs the ordered name pre-checks,
validation, store write THEN register (rolling the row fully back on a register
failure), one ``list_changed``, and the bus rebind fan-out. The response embeds
the per-worker fleet report under ``fanout``.

A preset's NAME is its identity everywhere — it IS the live tool binding, and every
reference keys on it deliberately; there are no surrogate ids.



# Delete a preset
Source: https://docs.tai42.ai/api-reference/presets/delete-a-preset

/openapi.json delete /api/presets/{name}
Delete a preset.

A non-conflicted record is soft-deleted and its base + branch tools torn down (one ``list_changed``);
a conflicted record is removed store-side ONLY (HARD delete + drop the quarantine entry), touching no
registration and firing no emit. Both branches fan the removal out on the bus and embed the per-worker
fleet report under ``fanout``.



# Get a preset
Source: https://docs.tai42.ai/api-reference/presets/get-a-preset

/openapi.json get /api/presets/{name}
The store record + the active ``fixed_kwargs`` + the ``uses`` / ``used_by`` cross-references.

404 for an absent name.



# Get a specific preset version
Source: https://docs.tai42.ai/api-reference/presets/get-a-specific-preset-version

/openapi.json get /api/presets/{name}/versions/{version}
One version of a preset by its integer version number.

A non-integer segment is a 400 and an unknown version a 404.



# List a preset's versions
Source: https://docs.tai42.ai/api-reference/presets/list-a-presets-versions

/openapi.json get /api/presets/{name}/versions
The full version history for a preset; 404 for an absent name.



# List live references to this preset
Source: https://docs.tai42.ai/api-reference/presets/list-live-references-to-this-preset

/openapi.json get /api/presets/{name}/referees
Every live reference a rename of this preset would strand — the SAME union the rename door blocks on.

The OTHER presets whose active body composes it, plus every registered referee
(platform wiring — schedules/hooks/routes/extensions/parks — and plugin holders).
Exposed so the UI can preflight a rename. 404 for an unknown preset, the same
existence check the rename door runs first; a referee raising propagates loudly,
exactly as at the rename gate.



# List presets
Source: https://docs.tai42.ai/api-reference/presets/list-presets

/openapi.json get /api/presets
One row per store-backed record (the presets plus the ``conflicted`` quarantined ones).

The population the presets management table shows.



# Rename a preset
Source: https://docs.tai42.ai/api-reference/presets/rename-a-preset

/openapi.json post /api/presets/{name}/rename
Rename a preset, ATOMIC (a preset's name IS its live tool name).

Runs create's ordered name pre-checks on the NEW name, BLOCKS with a 409 listing every referee if any
live reference composes the current name, binds the new tool BEFORE tearing the old one down, fires one
``list_changed``, and fans the rebind out NEW-first then the old removal. The response embeds the
primary rebind (new-name) fan-out report under ``fanout``; the old-name removal stays log-only.

A preset's NAME is its identity everywhere — it IS the live tool binding, and every
reference (preset bodies, platform wiring, plugin holders) keys on it deliberately;
rename integrity is enforced at THIS gate, and there are no surrogate ids.



# Roll a preset back to a version
Source: https://docs.tai42.ai/api-reference/presets/roll-a-preset-back-to-a-version

/openapi.json post /api/presets/{name}/rollback
Re-point the active version then reload and fan out.

409 if the record is conflicted, 404 for an absent name or version, 400 if
the target version cannot bind against the current live registry. The
response embeds the per-worker fleet report under ``fanout``.



# Save a new preset version
Source: https://docs.tai42.ai/api-reference/presets/save-a-new-preset-version

/openapi.json post /api/presets/{name}/versions
Save a new version (carry-forward sentinels on omitted fields) then reload and fan out.

409 if the record is conflicted, 404 for an absent name. The ``list_changed``
emit is GUARDED on a real change to the serialized wire tool OR its extension
combos. The response embeds the per-worker fleet report under ``fanout``.



# Set a preset version's tags
Source: https://docs.tai42.ai/api-reference/presets/set-a-preset-versions-tags

/openapi.json put /api/presets/{name}/versions/{version}/tags
Replace one version's ``tags`` annotation.

Tags are labels on an immutable version body, so this edits only the
annotation and never rebinds the live tool (no reload / no fan-out). 404 for
an unknown preset or version; a 501 ``NotSupportedError``
(versioning-not-configured) on a store-less deploy, exactly as the create
route refuses.



# Validate a preset draft (dry-run)
Source: https://docs.tai42.ai/api-reference/presets/validate-a-preset-draft-dry-run

/openapi.json post /api/presets/validate
Report whether a preset draft would be accepted, running the SAME pre-store verdict the write route would.

CREATE mode when no preset named ``name`` exists, VERSION mode when one does
(mode-resolved by a store lookup). Both verdicts return 200; only a malformed body is a
400.



# Load a stored resource by id, optionally rendering it
Source: https://docs.tai42.ai/api-reference/resources/load-a-stored-resource-by-id-optionally-rendering-it

/openapi.json get /api/resources/get
Load a stored resource by its id, optionally rendering it as a template.

Args:
    resource_id: The id (path) of the resource to load.
    kwargs: When omitted, the resource's loaded content is returned
        as-is. When provided (any dict, incl. ``{}``), text is rendered as a
        Jinja template with these variables; media raises loudly (``400``).

Returns:
    The loaded (and optionally rendered) content — text or a ``MediaBlock``.

A missing resource is a ``404``; a traversal-escaping id, a render of media, or
broken client-supplied Jinja is a ``400``. Genuine storage/transport failures
raise other types and propagate as a ``500``.



# Load a stored resource by id, optionally rendering it
Source: https://docs.tai42.ai/api-reference/resources/load-a-stored-resource-by-id-optionally-rendering-it-1

/openapi.json post /api/resources/get
Load a stored resource by its id, optionally rendering it as a template.

Args:
    resource_id: The id (path) of the resource to load.
    kwargs: When omitted, the resource's loaded content is returned
        as-is. When provided (any dict, incl. ``{}``), text is rendered as a
        Jinja template with these variables; media raises loudly (``400``).

Returns:
    The loaded (and optionally rendered) content — text or a ``MediaBlock``.

A missing resource is a ``404``; a traversal-escaping id, a render of media, or
broken client-supplied Jinja is a ``400``. Genuine storage/transport failures
raise other types and propagate as a ``500``.



# List platform runs
Source: https://docs.tai42.ai/api-reference/runs/list-platform-runs

/openapi.json get /api/runs
A newest-first, filterable page of the platform runs index.

Enumerated from the ``run_index`` table, so runs are listable without the
observability vendor. With the store OFF the honest answer is the empty page.
Each item carries ``traceId`` for a deep link to the vendor trace view.



# Prune the platform runs index
Source: https://docs.tai42.ai/api-reference/runs/prune-the-platform-runs-index

/openapi.json post /api/runs/prune
Delete runs-index rows older than the configured retention window; return the window and count pruned.

A no-op (nothing deleted) when the store is OFF or ``TAI_RUNS_INDEX_RETENTION_DAYS``
is unset — each reported in ``skipped``, mirroring the checkpoint-retention sweep's
disabled-retention posture (unset = rows kept forever).



# Get the sandbox identity and resolved policy
Source: https://docs.tai42.ai/api-reference/sandbox/get-the-sandbox-identity-and-resolved-policy

/openapi.json get /api/sandbox
Whether a sandbox provider is registered, plus the resolved security policy and live session count.



# Create a schedule
Source: https://docs.tai42.ai/api-reference/schedules/create-a-schedule

/openapi.json post /api/schedules
Schedule a caller-named tool to run on a cadence, or once now with no cadence — a run-ANY-tool door.

The caller supplies ``tool_name``, so reaching this is arbitrary-tool-execution
privilege (the recurring firing runs the named tool with real side effects). As a
"run any tool by name" door it is a tier-1 meta-executor, never projected to the MCP
surface — matching ``run_tool`` and ``submit_run``.

The four door-contract jqs make the schedule a parkable-driving door: a recurring fire evaluates
them each firing over the tool's arguments with ``$parked`` bound; a RUN-ONCE shape (no cadence)
honours them at the immediate create-time dispatch through the SAME door mechanism. A contract jq
requires ``execution_key`` — the identity a receiver-less recurring fire binds to rebind/resume a
park it raises.



# Delete a schedule
Source: https://docs.tai42.ai/api-reference/schedules/delete-a-schedule

/openapi.json delete /api/schedules/{schedule_name}
Delete the schedule named ``schedule_name``; raises 501 when no scheduling backend is present.



# Get the server date and time
Source: https://docs.tai42.ai/api-reference/schedules/get-the-server-date-and-time

/openapi.json get /api/schedules/server-datetime
Return the server's current date and time, read from the platform's own clock.



# List schedules
Source: https://docs.tai42.ai/api-reference/schedules/list-schedules

/openapi.json get /api/schedules
List the installed backend's schedules as ``ScheduleListRow`` dumps; 501 when no scheduling backend is present.

The backend tool's output is validated as ``list[ScheduleListRow]``; any other shape is a 500 naming
the first violation.



# A state's consumers
Source: https://docs.tai42.ai/api-reference/states/a-states-consumers

/openapi.json get /api/states/{name}/consumers
Everything that binds the state — every registered consumer family — as the Consumers tab reads it.

A consumer family the deployment cannot list is a labelled, muted row.



# A state's record statistics
Source: https://docs.tai42.ai/api-reference/states/a-states-record-statistics

/openapi.json get /api/states/{name}/stats
Record counts for a state — the total and the per-subject-kind breakdown.



# A subject's write audit trail
Source: https://docs.tai42.ai/api-reference/states/a-subjects-write-audit-trail

/openapi.json get /api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}/writes
One keyset page of a subject's write ledger.

``items`` (each entry's seq, timestamp, completed origin (door/actor/consumer/meta/run/
turn) and the paths it touched) and the ``next_cursor`` the next page reads from (null on
the last page).



# Apply an update-purpose template_jq program to a subject's record
Source: https://docs.tai42.ai/api-reference/states/apply-an-update-purpose-template_jq-program-to-a-subjects-record

/openapi.json post /api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}/template-jq/{program}
Apply an ``update``-purpose ``template_jq`` program to one subject.

Its jq returns a template-relative op batch applied through the same chokepoint as a
delta — regimes, the composing-shape guard, trace stamping and ``op_id`` idempotency all
hold. ``program`` may be unqualified or ``<template>.<name>``. An unknown program is a
404; an ambiguous unqualified name, an ``input``-purpose name, or a program that fails to
evaluate or returns the wrong shape is a 422.



# Apply ops to a subject's record
Source: https://docs.tai42.ai/api-reference/states/apply-ops-to-a-subjects-record

/openapi.json post /api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}/deltas
Apply an ordered op batch to a subject's document.

Refused if a whole-path write violates an attached path's regime; idempotent on a
replayed ``op_id``.



# Attach a template on a state
Source: https://docs.tai42.ai/api-reference/states/attach-a-template-on-a-state

/openapi.json put /api/states/{name}/attachments/{template}
Attach ``template`` on the state at the body's ``path`` with its parameters and static declarations.

Recomposes and validates the effective schema in one transaction.



# Check a state's stored records against its schema
Source: https://docs.tai42.ai/api-reference/states/check-a-states-stored-records-against-its-schema

/openapi.json get /api/states/{name}/records/check
A keyset page of the stored records that do NOT fit the state's current effective schema.

``checked`` reports how many records the page read; ``items`` are only the misfits, each with
every reason. Pages like the subjects listing (optionally one ``kind``); ``held`` names the
saves held by a failed pending save that the page skipped.



# Create or re-declare a state
Source: https://docs.tai42.ai/api-reference/states/create-or-re-declare-a-state

/openapi.json put /api/states/{name}
Upsert a state declaration; the ``name`` is taken from the path.

With records present only additive schema changes are accepted — a narrowing is refused
while records exist. The state's pending saves are applied first; a save held by a failed
save counts as records present and an accepted re-declare names it in ``held``.



# Create or replace a state template
Source: https://docs.tai42.ai/api-reference/states/create-or-replace-a-state-template

/openapi.json put /api/state-templates/{name}
Upload a state-template document; the ``name`` is taken from the path.

An existing name without ``replace`` is refused so an overwrite is deliberate.



# Delete a state
Source: https://docs.tai42.ai/api-reference/states/delete-a-state

/openapi.json delete /api/states/{name}
Delete a state with its records, attachments and aliases; refused while a consumer binds it.



# Delete a state template
Source: https://docs.tai42.ai/api-reference/states/delete-a-state-template

/openapi.json delete /api/state-templates/{name}
Delete a state-template document; refused while it is still attached.



# Detach a template from a state
Source: https://docs.tai42.ai/api-reference/states/detach-a-template-from-a-state

/openapi.json delete /api/states/{name}/attachments/{template}
Remove a template's attachment and recompose the effective schema — nothing else.

Consults the detach referees FIRST: a template still named by a live door binding (a
preset version, a conversation config, a hook, a schedule) is a 409 that detaches nothing
and lists the referencing bindings — the attach-at-save contract's referee, so a binding
never faults at run time on a template detached out from under it.



# Discard a failed pending state save
Source: https://docs.tai42.ai/api-reference/states/discard-a-failed-pending-state-save

/openapi.json delete /api/state-pending-saves/{id}
Drop a failed pending save for good: its record writes and deferred calls are never applied.



# Erase a subject's record
Source: https://docs.tai42.ai/api-reference/states/erase-a-subjects-record

/openapi.json delete /api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}
Erase a subject's record; a fresh read then returns ``null``.



# Evaluate an input-purpose template_jq program for a subject
Source: https://docs.tai42.ai/api-reference/states/evaluate-an-input-purpose-template_jq-program-for-a-subject

/openapi.json get /api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}/template-jq/{program}
An ``input``-purpose ``template_jq`` program's result for one subject — its jq over the record.

``params`` supplies the program's declared parameters. ``program`` may be unqualified or
``<template>.<name>``. An unknown program (or a subject with no attachment declaring it)
is a 404; an ambiguous unqualified name, an ``update``-purpose name, an undeclared param
or a program that fails to evaluate is a 422. Read-only.



# Fold one subject into another
Source: https://docs.tai42.ai/api-reference/states/fold-one-subject-into-another

/openapi.json post /api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}/fold
Fold this subject's record into the ``into`` subject under ``mode`` (an alias the reads resolve through).

Refused on a self-fold, a cycle, or a merge that no longer validates.



# Get a state
Source: https://docs.tai42.ai/api-reference/states/get-a-state

/openapi.json get /api/states/{name}
One state's served declaration.

Base ``schema``, ``effective_schema``, ``subject_kinds``, ``default_subject_kind``, its
``attachments``, computed ``regimes`` and ``updated_at`` (the ISO timestamp of its last
write).



# Get a state template
Source: https://docs.tai42.ai/api-reference/states/get-a-state-template

/openapi.json get /api/state-templates/{name}
One state-template document by name.



# Get a state's attachment
Source: https://docs.tai42.ai/api-reference/states/get-a-states-attachment

/openapi.json get /api/states/{name}/attachments/{template}
One template's attachment on the state — its path, resolved parameters and declarations.

The same row the list serves. A template not attached on the state is a 404.



# List a state's attachments
Source: https://docs.tai42.ai/api-reference/states/list-a-states-attachments

/openapi.json get /api/states/{name}/attachments
Every template attached on the state — its path, resolved parameters and declarations.



# List a state's subjects
Source: https://docs.tai42.ai/api-reference/states/list-a-states-subjects

/openapi.json get /api/states/{name}/subjects
A keyset page of the subjects holding a record for the state, optionally one ``kind``.



# List declared states
Source: https://docs.tai42.ai/api-reference/states/list-declared-states

/openapi.json get /api/states
Every declared state, base + composed effective schema included, each with its ``updated_at``.

The ``updated_at`` timestamp is the Updated column.



# List pending state saves
Source: https://docs.tai42.ai/api-reference/states/list-pending-state-saves

/openapi.json get /api/state-pending-saves
Outstanding pending state saves newest first, with the outstanding and failed totals.

``status`` ``failed`` lists the failed saves only; ``outstanding`` (or none) lists every save
still outstanding. A page holds at most ``limit`` saves; ``cursor`` continues from a page's
``next_cursor``.



# List state templates
Source: https://docs.tai42.ai/api-reference/states/list-state-templates

/openapi.json get /api/state-templates
Every platform state-template document (the reusable schema fragments), each with the catalog columns.

``attached_to`` (the number of states it is attached on) and ``shipped_default``
(whether it is an unedited shipped default).



# Merge into a subject's record
Source: https://docs.tai42.ai/api-reference/states/merge-into-a-subjects-record

/openapi.json patch /api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}
Shallow top-level merge of ``patch`` into a subject's document.



# Prune expired state records
Source: https://docs.tai42.ai/api-reference/states/prune-expired-state-records

/openapi.json post /api/state-retention/prune
Delete every record past its state's ``retention_days`` horizon.

Returns the per-state deleted counts and the saves held by a failed save whose records it kept.



# Read a subject's record
Source: https://docs.tai42.ai/api-reference/states/read-a-subjects-record

/openapi.json get /api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}
One subject's record, or ``null`` when none exists.

An unknown ``person`` subject is a refusal, never an empty document. A subject ``key``
that contains ``/`` (a thread key is a thread id) is percent-encoded as one path segment;
this holds for every single-record door.



# Replace a subject's record
Source: https://docs.tai42.ai/api-reference/states/replace-a-subjects-record

/openapi.json put /api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}
Replace a subject's whole document with ``data`` (validated against the effective schema).



# Retry a failed pending state save
Source: https://docs.tai42.ai/api-reference/states/retry-a-failed-pending-state-save

/openapi.json post /api/state-pending-saves/{id}/retry
Requeue a failed pending save and apply its records now; answer its status after that.

``applied`` when the save landed whole and is gone; ``calls`` or ``running`` while its calls
are queued or running; ``failed`` (with ``last_error``) when it failed again.



# Search a state's records
Source: https://docs.tai42.ai/api-reference/states/search-a-states-records

/openapi.json post /api/states/{name}/records/search
A keyset page of records whose document contains ``filters`` (a JSON containment match).



# Update an attachment's declarations
Source: https://docs.tai42.ai/api-reference/states/update-an-attachments-declarations

/openapi.json patch /api/states/{name}/attachments/{template}
Replace an attachment's static declaration values and reconcile ``options``.

Re-runs the attach validators and reconcilers and recomposes the effective schema.



# Validate a candidate record against a state's schema
Source: https://docs.tai42.ai/api-reference/states/validate-a-candidate-record-against-a-states-schema

/openapi.json post /api/states/{name}/records/validate
Check a candidate document against the state's effective schema without storing it.

The request body IS the document (any JSON). A document that does not fit is answered with a
``200`` body ``{fits: false, reasons: [...]}`` naming every misfit; a non-object body or an
effective schema with a broken ``$ref`` is a ``422``, and an undeclared state a ``404``.



# Delete a storage directory
Source: https://docs.tai42.ai/api-reference/storage/delete-a-storage-directory

/openapi.json delete /api/storage/dirs/{dir_path}
Remove a directory subtree from the store; the render state under it is evicted fleet-wide.

This worker evicts whatever the outcome. A failure before deletion begins — a missing
directory (``404``) or a rejected path (``400``) — broadcasts nothing. A failure once
deletion may have begun leaves the store partially changed, so the eviction still fans
out before the error propagates (a ``FleetBroadcastError`` carrying the fleet report).



# Delete a storage resource
Source: https://docs.tai42.ai/api-reference/storage/delete-a-storage-resource

/openapi.json delete /api/storage/resources/{resource_id}
Remove one object from the store; its render state is evicted fleet-wide.



# Download a storage resource
Source: https://docs.tai42.ai/api-reference/storage/download-a-storage-resource

/openapi.json get /api/storage/resources/{resource_id}/content
Serve the raw object bytes as a file download.

A content server (raw bytes + a Content-Disposition attachment header, not the
``{"data": ...}`` envelope), so it stays a native handler rather than an
operation adapter.



# Get the storage provider identity
Source: https://docs.tai42.ai/api-reference/storage/get-the-storage-provider-identity

/openapi.json get /api/storage
Report the registered provider's identity, or ``present: false`` when none is installed.

A ``200``, so the UI renders the empty state without an error.



# List storage resources
Source: https://docs.tai42.ai/api-reference/storage/list-storage-resources

/openapi.json get /api/storage/resources
List the sorted resource ids from the active storage provider.



# Stat a storage resource
Source: https://docs.tai42.ai/api-reference/storage/stat-a-storage-resource

/openapi.json get /api/storage/resources/{resource_id}/stat
Return the resource's inferred content type.



# Upload a storage resource
Source: https://docs.tai42.ai/api-reference/storage/upload-a-storage-resource

/openapi.json post /api/storage/resources
Store text OR base64-decoded bytes under ``resource_id`` (overwrite on reuse).

The type/shape validation the tool schema cannot express — a non-empty ``id``,
exactly one content field, and each field's type — is enforced here so the MCP
tool edge carries it too; the HTTP route's extractor passes the raw body through
to the same checks. The stored id's render state is evicted fleet-wide.



# List the registered sub-MCP apps
Source: https://docs.tai42.ai/api-reference/sub-mcp/list-the-registered-sub-mcp-apps

/openapi.json get /api/sub-mcp
List the registered sub-MCP apps from the durable store, keyed by slug, with each served mount.



# Register or reload a sub-MCP app
Source: https://docs.tai42.ai/api-reference/sub-mcp/register-or-reload-a-sub-mcp-app

/openapi.json post /api/sub-mcp
Register or reload the sub-MCP app ``slug`` exposing ``tools`` on ``transport``; an unknown tool is a 404.



# Unregister a sub-MCP app
Source: https://docs.tai42.ai/api-reference/sub-mcp/unregister-a-sub-mcp-app

/openapi.json delete /api/sub-mcp/{slug}
Unregister the sub-MCP app ``slug`` and tear down its lifespan; an unknown slug is a 404.



# List pluggable-kind status
Source: https://docs.tai42.ai/api-reference/system/list-pluggable-kind-status

/openapi.json get /api/system/kinds
List the status of every pluggable kind.



# Clear the template render cache
Source: https://docs.tai42.ai/api-reference/templates/clear-the-template-render-cache

/openapi.json post /api/clear-templates-cache
Drop every compiled template from the render cache, fleet-wide.

The manual escape hatch that pairs with the automatic per-key eviction: it
broadcasts a ``clear_template_cache`` op so every worker cold-starts its compiled
cache, not only the one that served this call. The response embeds the per-worker
fleet report.



# Delete a template
Source: https://docs.tai42.ai/api-reference/templates/delete-a-template

/openapi.json post /api/delete-template
Delete the stored template at ``path``.

Idempotent: an already-absent path is a no-op success (the store treats a
missing template as a no-op rather than raising), so this returns ``200``.

The store delete is followed by a fleet ``evict_template`` broadcast so every
worker drops the stale compilation, not only the one that served this call; the
response embeds the per-worker fleet report.



# Delete a template directory
Source: https://docs.tai42.ai/api-reference/templates/delete-a-template-directory

/openapi.json post /api/delete-template-dir
Delete every stored template under the directory ``path``.

Unlike the idempotent single-template delete, a directory matching nothing is a loud
``404`` (the provider's ``FileNotFoundError``). A key resolving to the template ROOT
would wipe the whole store, so it is refused with a ``400`` HERE, ahead of the provider;
a provider reporting a root violation as ``ValueError`` maps to ``400`` too.



# Fetch a template and its schema
Source: https://docs.tai42.ai/api-reference/templates/fetch-a-template-and-its-schema

/openapi.json post /api/template
Return a stored template's content and its inferred input schema.

A missing stored template is a ``404`` (never a leaked storage ``500``); a
stored template with broken Jinja is author error — the schema inference parses
it — surfaced as a ``400``. Genuine storage failures raise other types (``500``).

A renderable template always reads back ``200``: when type inference cannot
describe it, the schema degrades to variable names carrying an
``x-tai42-inference: partial`` marker rather than failing the read.



# List templates
Source: https://docs.tai42.ai/api-reference/templates/list-templates

/openapi.json get /api/templates
List the stored template ids/paths from the active storage provider.



# Render a template
Source: https://docs.tai42.ai/api-reference/templates/render-a-template

/openapi.json post /api/render-template
Render the one authored ``text`` — inline ``content`` OR a stored ``id`` — with its ``kwargs``.

``text`` carries EXACTLY ONE source: its own type refuses neither and both, so a
caller supplying the wrong shape is a loud ``400`` at the edge. A stored ``id`` that
cannot be fetched is a ``404`` naming that id; broken client-supplied Jinja (a syntax
error, a sandbox-blocked dunder traversal → ``SecurityError``, an undefined access)
is author error → ``400``. Genuine storage failures raise other types (``500``).



# Upload a template
Source: https://docs.tai42.ai/api-reference/templates/upload-a-template

/openapi.json post /api/upload-template
Write ``content`` to the template store under ``path`` (create or overwrite).

The write target is guarded against a root escape before it reaches the store.

A template id cannot also name a directory that still holds templates: an
upload whose ``path`` collides with such a directory is refused with a ``409``
naming the templates in the way, so the caller deletes them first.

The store write is a single durable act, but the compiled template is held in a
per-worker cache, so the write is followed by a fleet ``evict_template`` broadcast:
this worker's local apply persists and evicts, and every sibling drops the stale
compilation on dispatch. The response embeds the per-worker fleet report so a
caller has deterministic proof the eviction propagated; an unconfirmed worker is
logged loudly, matching the reload broadcast.



# Get a background tool run's status and result
Source: https://docs.tai42.ai/api-reference/tool-runs/get-a-background-tool-runs-status-and-result

/openapi.json get /api/tool-runs/{run_id}
Get a background tool run by ``run_id``; a restricted caller may read only its own runs.



# List background tool runs for a tool
Source: https://docs.tai42.ai/api-reference/tool-runs/list-background-tool-runs-for-a-tool

/openapi.json get /api/tool-runs
List the recent runs for one tool, newest first.

A restricted caller reads its OWN per-identity index (complete within its own
bound — never truncated by other identities' volume that saturates the shared
window); an unrestricted caller reads the shared index unchanged. An empty list
is the honest answer to "my runs of this tool" — this filters a collection to the
caller's own slice (distinct from GET-by-id, which raises ``403`` for a NAMED run
owned by another identity).



# Submit a tool for background execution
Source: https://docs.tai42.ai/api-reference/tool-runs/submit-a-tool-for-background-execution

/openapi.json post /api/tool-runs
Submit a tool for background execution — returns ``202 {run_id}`` at once.

Runs the tool through the same seam the sync door uses.

The submitted tool is authorized against the caller with the full tool-edge decision
before anything is recorded, so a fenced/secret target is admin-only here exactly as
at the sync door and the MCP edge.

``subject`` names the addressed subject the detached run's async parks index under: it is
handed to the spawned supervisor, which deposits it as the run's ``door="api"``
``StateContext`` so a park is findable and resumable by a later run on the same subject.



# Create a folder
Source: https://docs.tai42.ai/api-reference/tool_meta/create-a-folder

/openapi.json post /api/tool-meta/folders
Create a folder under ``parent_id`` (``null`` = a root folder).

A blank name is a 400, an unknown ``parent_id`` a 400, and a sibling already holding the name a 409.



# Delete a folder
Source: https://docs.tai42.ai/api-reference/tool_meta/delete-a-folder

/openapi.json delete /api/tool-meta/folders/{folder_id}
Delete an EMPTY folder.

An unknown folder is a 404; a folder still holding subfolders or overlay rows is a 409 (empty it first).



# Delete a tool's overlay row
Source: https://docs.tai42.ai/api-reference/tool_meta/delete-a-tools-overlay-row

/openapi.json delete /api/tool-meta/tools/{tool_name}
Drop the overlay row for ``tool_name``.

Idempotent — deleting a tool with no row is a no-op, not an error (most tools never own one).



# List the tool-metadata overlay
Source: https://docs.tai42.ai/api-reference/tool_meta/list-the-tool-metadata-overlay

/openapi.json get /api/tool-meta
The whole overlay in one read: every folder (the flat tree) plus every per-tool row.

The UI builds the tree and merges the rows against the live tool list client-side.



# Move a folder
Source: https://docs.tai42.ai/api-reference/tool_meta/move-a-folder

/openapi.json post /api/tool-meta/folders/{folder_id}/move
Re-parent a folder (``null`` = move to root).

An unknown folder or parent is a 404, a move that would form a cycle a 400, and a sibling
collision at the destination a 409.



# Rename a folder
Source: https://docs.tai42.ai/api-reference/tool_meta/rename-a-folder

/openapi.json post /api/tool-meta/folders/{folder_id}/rename
Rename a folder in place.

A blank name is a 400, an unknown folder a 404, and a sibling collision a 409.



# Upsert a tool's overlay
Source: https://docs.tai42.ai/api-reference/tool_meta/upsert-a-tools-overlay

/openapi.json patch /api/tool-meta/tools/{tool_name}
Merge-patch the overlay row for ``tool_name`` (create it if absent).

``patch`` holds ONLY the fields the caller sent; each is applied over the current row (or
the empty defaults when none exists), absent fields unchanged. A blank
``display_name`` is refused; a present-null clears; a present ``tags`` or
``badges`` array replaces that set. An unknown ``folder_id`` is a loud 400.



# Get one tool's input/output schema
Source: https://docs.tai42.ai/api-reference/tools/get-one-tools-inputoutput-schema

/openapi.json get /api/tools/{tool_name}/schema
One tool's input/output/description view (unknown name → 404).



# Get the input/output schema of every tool
Source: https://docs.tai42.ai/api-reference/tools/get-the-inputoutput-schema-of-every-tool

/openapi.json get /api/tools-schema
The input/output/description view of every registered tool, keyed by name.



# List each tool's native tags, declared visibility, and badges
Source: https://docs.tai42.ai/api-reference/tools/list-each-tools-native-tags-declared-visibility-and-badges

/openapi.json get /api/tools/tags
The per-tool native-``tags`` map plus the plugin-declared visibility and capability badges.

One ``{name, tags, hidden, badges, schedulable}`` entry per registered tool, ``tags`` and ``badges`` each
sorted for a stable wire order. ``hidden`` is the tool's OWN declaration, read from the
FastMCP ``meta`` under ``TOOL_META_HIDDEN`` (a tool that never declared it is
not hidden); ``badges`` is likewise the tool's OWN declared INFORMATIONAL capability badges,
read from ``meta`` under ``TOOL_META_BADGES`` (a tool that declared none carries an empty list).
The tool_meta overlay's tri-state override and its own badge set are merged on top
client-side; this read exposes only the declaration. ``schedulable`` is whether the tool's
``<name>_schedule_task`` vehicle is registered, so a client never spells the suffix. Additive to
the flat names contract; a tool with no tags carries an empty list.



# List the registered tool names
Source: https://docs.tai42.ai/api-reference/tools/list-the-registered-tool-names

/openapi.json get /api/tools
The sorted registered tool names.



# Reload one app tool from its stored definition
Source: https://docs.tai42.ai/api-reference/tools/reload-one-app-tool-from-its-stored-definition

/openapi.json post /api/tools/reload
Re-register one app tool (e.g. kind "example_tool") from its current stored definition.

Applied on this worker and broadcast to the fleet (all workers, or only
``targets``); each worker re-reads the definition itself, so the op carries only
the kind and name. The response embeds the per-worker fleet report.



# Remove one app tool from the live registry
Source: https://docs.tai42.ai/api-reference/tools/remove-one-app-tool-from-the-live-registry

/openapi.json post /api/tools/remove
Remove one app tool (e.g. kind "example_tool") from the live registry.

Applied on this worker and broadcast to the fleet (all workers, or only
``targets``); the response embeds the per-worker fleet report.



# Run a registered tool synchronously
Source: https://docs.tai42.ai/api-reference/tools/run-a-registered-tool-synchronously

/openapi.json post /api/run-tool
Execute an arbitrary registered tool with REAL side effects.

Reaching this route is full-execution privilege — the Studio key runs any
registered tool. Per-tool scoped keys are not supported.

With the caller's own execution identity bound below, the dispatch ALSO takes
the per-call execution decision the fire seam runs (an AND-gate over this
route's own authz — it can only deny more, never less), and a connector-backed
tool resolves its managed credential exactly as a fire would. Both are
fire-parity, not new privilege; when the bind degrades to unbound the dispatch
runs with no subject context.

The tool starts through the shared :func:`~tai42_skeleton.interactions.visit.visit`, under
the ``door="api"`` :class:`StateContext` the caller's named ``subject`` deposits: a tool
whose async ask parks then indexes under that subject and answers ``asks``/``parked`` rather
than raising. A tool that never parks answers ``result`` carrying its value.



# The agenda state template
Source: https://docs.tai42.ai/babelfish/agenda

The shipped state template for conversations that handle many intents per inbound, each living through phases across turns, with one composed reply per turn.

The **agenda** is a shipped [state template](/babelfish#state-templates) for a
conversation that handles MANY intents per inbound, each intent living through **phases**
across several turns, with dependencies between phases, and **one composed reply** per
turn. An *intent* is the flow's job for an inbound — not the user's wish — so a single
message can open several. The agenda is data end to end: a state-template document (its
schema, write regimes, declarations, and [template jq](/babelfish#state-templates)) plus
the bulky jq bodies beside it. A client attaches it to a state and drives it from a flow's
per-node [bindings](/babelfish#binding-a-node-to-a-state) — input injections read the
`input` template jq to decide what is due, and `update` template jq write the ledger after
each step. The pattern is client-agnostic: a client declares only its intents, phases,
follow-ons, and reply parts — the **manifest** — as the attachment's declarations.

> [!NOTE]
>
> The agenda ships with babelfish as resource files under
> `resources/state-template/agenda/` — the one `state-template` document and its template jq
> bodies — not as engine code and not as a flow. It is installed like any other state
> template (`tai state-templates put`, then attach it to a state). Babelfish is proprietary
> and licensed commercially; the agenda ships with it, not on PyPI.

## What the template stores

The template's schema fragment holds four keyed lists and three single slots. The lists are
under the `composing` writer regime — many keyed writers per list — while `turn_talk`,
`last_outbound`, and `transcript` are each `single`, one whole-object writer:

* **`ledger`** — one row per **intent**: `id`, `kind`, an optional **`item`** (the intent's
  item identity when the kind declares one intent per item; `null` for an itemless kind),
  `source` (`inbound` | `event` | `tick` | `standing` | `follow_on` — a record derives
  `tick` when its event turn's inbound source is `event:tick`, the event kind a schedule
  adapter posts through the event door), the classifier's extracted `fields`, a `rank` (the
  order among open intents of a sequence group), a `minted_run` `{run, pass}`, and a
  `closed` `{resolution, sent_run}` mark that compose writes. A closed intent is **pruned**
  at the next mint once no open intent still names one of its phases (below).
* **`ledger_phases`** — one upserted row per phase key `<intent id>:<item>:<phase>`,
  carrying the **`outcome`** label the flow returned, its derived class
  (`resolution` — settled: `done`, or one of the manifest's declared not-done names) or wait
  (`wait_for` — `who` a party, or `waits_on` another phase
  key when `who` is `phase`), the outcome `fields`, the writing `run`/`pass`, and a `sent`
  run stamp compose sets.
* **`ledger_inbound`** — one row per binding of an inbound span to a phase; `relation`
  records HOW it bound (`answers`, `ambiguous`, `event`, `yes_no`, `form`, `option`,
  `reactivate`, `follow_on`), and an ambiguous binding carries an **`attempt`** counter (the
  clarify round, from 1).
* **`turn_talk`** — the classifier's free text for THIS turn (`{run, text}`), an input to
  the compose talk slot.
* **`last_outbound`** — a single `{run}` slot compose sets to the [turn id](#two-ids-named-run)
  whenever it emits any outbound content (a part or the turn's talk); a fully silent turn
  (no part and no talk) re-emits the prior pointer rather than erasing it. It names the last
  run whose reply emitted anything; a bare yes/no binds only to a wait whose own `sent`
  stamp equals that run.
* **`transcript`** — `{lines: [{role, text, run}]}`, the composed-talk window. Compose is
  the sole writer — the platform exposes no thread read to plugins — appending a `user`
  inbound line and, when it speaks, an `assistant` outbound line each turn, truncated to the
  talk slot's `transcript_window_lines`. The talk slot reads the PRIOR window as context.

### Two ids named `run`

A `ledger` and `ledger_phases` row each carry a field called `run`, and the trace stamp
carries another — they mean different things, and the page states the contrast so a dump
reads right:

* A row's own `run` (and `minted_run.run`) is the **turn id** — the unit of work, the
  turn the row was written for.
* `_trace.run` is the writing run's **session id** — the client flow run in which the
  update template jq wrote the row.

### The trace

`trace.enabled` is `true`, so every row carries a `_trace` object:
`{meta, run, turn, inbound, at}` — the writer-supplied `meta`, the run's session id, the
turn id, the turn's inbound id, and the write time. The engine supplies `meta: {node: <node
id>}`, so the writing node reads at `_trace.meta.node`. Because a `composing` list admits
several keyed writers per row kind and nothing statically pins one node per field, the trace
stamp is the evidence a dump needs for **which node wrote which row**.

Record ids are `<turn.inbound.id>/<kind>/<n>`, where `n` is the 0-based mint ordinal within
the run across every source (inbound spans, standing conditions, follow-ons) — one counter
takes the next ordinal for every row it mints, so `n` is unique per turn. Provenance lives in
`source` and `event`, never in the id. Both the mint and the record update derive `source`
through the template's shared `turn_source` input jq — `tick` when the inbound source is
`event:tick`, `event` for any other event turn, else `inbound`.

## The manifest a client declares

The attachment's `declarations` carry `intents`, `phases`, `outcomes`, and `parties` — the
wait parties beyond the engine's own — plus `clarify_kind`, `unmatched_kind`, `clarify_limit`
and `talk_slot`. The schema admits no other key. A placeholder manifest — kinds `status` and
`utilities`, the synthetic vocabulary this page uses throughout:

```jsonc theme={null}
{
  "intents": [
    {
      "kind": "status",                          // the classifier labels a span "status"
      "description": "the user asks after an open item",
      "sources": ["inbound", "event"],           // a message span OR an event-door turn
      "item": {"field": "ref"},                  // ONE INTENT PER ITEM: the item id is the
                                                 //   span's extracted "ref" (exclusive with "items")
      "fields": {                                // the per-kind classifier extraction schema,
        "ref": {"type": "string"}                //   merged into the forced span object beside "text"
      }
    },
    {
      "kind": "utilities",
      "description": "the user asks to run a utility",
      "sequence": "chores",                      // a SEQUENCE GROUP: one open utilities intent
                                                 //   fires per pass, in rank order (null = parallel)
      "sources": ["inbound"],
      "items": [],                               // a fixed item list; [] = the single implicit item "_"
      "standing": null                           // a jq predicate STRING; a standing kind is minted
                                                 //   when it holds and no intent of the kind is open
    }
  ],
  "phases": [
    {
      "key": "check", "kind": "status", "item": "_",
      "predecessor": null,                       // a phase key, "record", {phase, outcomes} (labels
                                                 //   that reach the successor), or null (a first phase)
      "expected_input": {                        // wake this wait on a correlated event
        "kind": "event",
        "event": "settle",                       //   the event kind that correlates here
        "key": "ref",                            //   the payload key whose value names the item
        "via": "$key"                            //   a jq over the flow root ($key = the payload's key value);
                                                 //     absent = the key value itself
      },
      "outcomes": [                              // the outcome LABELS this phase can record
        {"outcome": "done", "resolution": "done", "fields": ["state"],
         "follow_on": {"mint": "utilities", "item_field": "ref"}},   // open a utilities intent for this item
        {"outcome": "declined", "resolution": "declined", "fields": ["reason"]},
                                                 //   a NOT-DONE resolution, its name declared in
                                                 //   parameters.resolutions: the chain stops here
        {"outcome": "waiting", "wait_for": {"who": "partner"}, "fields": ["eta"]}
                                                 //   "partner" is a party declared below
      ]
    },
    {
      "key": "run", "kind": "utilities", "item": "_",
      "ordering_waits": [                        // {kind, phase} gates ("*" = every phase of the kind)
        {"kind": "status", "phase": "check"}     //   fires only when no status.check is still pending
      ],
      "expected_input": {
        "kind": "yes_no",
        "follow_ons": {                          // keyed by the answer value
          "no": {"reactivate": "run"}            //   "no" re-activates this phase to ask again
        }
      },
      "outcomes": [
        {"outcome": "confirm", "wait_for": {"who": "user"}, "fields": []},
        {"outcome": "done", "resolution": "done", "fields": ["result"]}
      ]
    }
  ],
  "outcomes": [
    {"kind": "status", "phase": "check", "outcome": "done",
     "part": {"kind": "text", "text": "status/check/done",   // one content-store template id
              "fields": ["state"], "order": 0}},
    {"kind": "status", "phase": "check", "outcome": "declined",
     "part": {"kind": "text", "text": "status/check/declined",
              "fields": ["reason"], "order": 0}},
    {"kind": "status", "phase": "check", "outcome": "waiting",
     "part": {"kind": "talk", "fields": ["eta"], "to": "user", "order": 0}},
    {"kind": "utilities", "phase": "run", "outcome": "confirm",
     "part": {"kind": "options",
              "text": "utilities/run/confirm",
              "options": {"fixed": [{"value": "yes", "label": "utilities/run/yes"},
                                    {"value": "no", "label": "utilities/run/no"}]},
                                    //   a fixed label, when present, is a template id too
              "order": 0}},
    {"kind": "utilities", "phase": "run", "outcome": "done",
     "part": {"kind": "text", "text": "utilities/run/done",
              "fields": ["result"], "order": 0}}
  ],
  "parties": ["partner"],                         // bare names: the wait parties beyond the
                                                  //   engine's own "user" and "phase"; a
                                                  //   label's wait_for.who names one
  "clarify_kind": "clarify",                      // the generic kind an ambiguous span mints
  "unmatched_kind": "unmatched",                  // the kind a no-hit / many-hit event or no-hit form mints
  "clarify_limit": 3,                             // clarify rounds before "unresolved" is recorded
  "talk_slot": {                                  // the composed-talk slot (null = off)
    "prompt_ref": "agenda/talk_prompt",           // one content-store template id
    "transcript_window_lines": 10
  }
}
```

### Intents

An intent declares its `kind`, classifier `description`, an optional `sequence` group, its
`sources`, a `standing` predicate, and EITHER `items` (a fixed list; empty means the single
implicit item `_`) OR `item {field}` (one intent per item, the item identity read from a
classifier-extracted field — **exclusive** with `items`). A kind may also declare
`fields {<name>: <JSON-Schema>}`, the per-kind extraction schema merged into the classifier's
forced per-span object beside the mandatory `text`; an `item.field`, and every `rank.match`
key targeting the kind, must name one of those `fields`. A kind with `item {field}` is
single-item in the phase sense (its `item` segment is `_`); the item identity lives on the
ledger row, not in the phase key.

An intent's `standing` is a jq predicate **string** that decides whether a standing intent
of the kind should be open. Because it reads a **sibling state** — a value on another state
the client also binds, such as an opt-in flag — it lives in the **client's flow binding over
that state**, not in the agenda template (a template-scoped input jq sees only its own
attached subtree). The client's mint step evaluates it each pass and opens one intent of the
kind when it holds and none of the kind is already open (a `null` predicate contributes no
intent).

An intent's `sources` lists the record sources the kind admits — `inbound` a classifier
span, `event`/`tick` an event-door turn. When non-empty the record update ENFORCES it: a span
minted for the kind from a source the list excludes raises
`agenda-record: kind <kind> does not admit source <source>` (a `standing` or `follow_on`
record is exempt — those are not inbound sources).

### Phases, labels, and follow-ons

A **phase** names its `key`, `kind`, `item`, a `predecessor`, its `ordering_waits`, an
optional `expected_input`, and `outcomes` — the outcome **labels**
the phase can record. A phase names no handler — the flow runs its handler for the phase and
returns the outcome. A `predecessor` is a phase key (satisfied when that phase resolves
`done`), `"record"` (the intent's item order — satisfied once the earlier items' same phase
is settled in any way), a `{phase, outcomes}` object (satisfied when the predecessor phase's
current outcome is one of the named labels), or `null` (a first phase). `ordering_waits` is a
list of `{kind, phase}` cross-intent gates, `phase` `"*"` meaning every phase of the kind. An
`expected_input` declares its `kind` (`yes_no` | `text` | `option` | `form` | `event`) and
`follow_ons` keyed by the answer value. An `event` input is `{kind: "event", event, key,
via?}`: `event` is the event kind that correlates here, `key` the payload key whose value
names the item, and an optional `via` a jq program over the flow root (with `$key` bound to
the payload's `key` value). For an **item kind** (one-per-item, or a static-item phase) `via`
must yield the wait's item — the ledger row's item (`item_of`) for a one-per-item kind, else
the phase key's item segment — and the event binds the wait naming it; a `via` yielding
nothing binds no item wait, and an absent `via` matches the `key` value itself. For an
**itemless kind** (item segment `_`) a `via` yielding `null` — which a wait that declares no
`via` also yields — means **this event is ours** and binds the kind's single open expectation,
while a `via` yielding the empty no-value (jq `empty`) means **not ours** and leaves the event
unmatched. An event whose key matches **zero or several** waits binds nothing and mints one
`unmatched_kind` record; a payload missing `key` raises `agenda: event <kind> carries no
'<key>'`.

Each **label** is `{outcome, resolution? | wait_for {who}, fields, follow_on?}`, declaring
exactly one of `resolution` (a class) or `wait_for` (a party). A `resolution` is one of two
classes: **`done`**, the class the engine names, whose successors are reached and whose chain
continues; or a **not-done** resolution, which stops the chain — the intent runs out of open
phases, closes, and compose speaks that resolution. The engine names no not-done class of its
own: every not-done name is declared by the deployment in
[`parameters.resolutions`](#the-parameters) and referenced by name from a label. A `wait_for`
names the party holding the wait: `user` and `phase` are the engine's own (`who: "phase"`
waits on another phase named at run time by the handler's `waits_on`), and every other party
is declared in the manifest's `parties` list and referenced there by name. `fields` are the
fields the label carries; an optional `follow_on` fires when the label is recorded. A
follow-on is exactly one action:

```jsonc theme={null}
{"mint": "utilities", "item_field": "ref"}     // open an intent of a kind; item_field = the
                                               //   source field whose value is the item to target
{"reactivate": "run"}                          // re-activate an earlier phase of the same intent
{"close": {"kind": "utilities",                // settle ANOTHER open intent with a declared resolution
           "item_field": "ref",                //   target the open (kind, item) intent by a source field…
           "outcome": "deferred"}}             //   …or "item": <static id> on an items-list kind,
                                               //   the outcome a declared not-done resolution
{"rank": {"kind": "utilities",                 // reprioritise an open intent of a SEQUENCED kind
          "ordinal": 3, "match": null,         //   exactly one of ordinal (n-th open, 1-based) / match (field equality)
          "first": true, "rank": null}}        //   first → below the group's current minimum; else the given number
```

An `item_field` on a `mint` **binds** the open `(kind, item)` intent's waiting phase (else
its next reached-unsettled phase, else mints a fresh record carrying that `item`); an
`item_field` on a `close` settles the open intent of that `(kind, item)`.

A `mint`'s `item_field` may carry a **list**: the mint then **fans out**, applying that same
match-else-mint rule once PER ELEMENT in the same pass — one record (or bind) per element, each
carrying its element as `item` and starting its own pass count. An empty list places nothing;
an absent value still raises. A fan-out targets a kind that declares `item {field}` (one intent
per item), so each record carries a single element — a list into any other kind raises at
attach, as does a list on a `close`, which names one item.

A follow-on rides an outcome label's `outcomes[].follow_on`, and a label's readable fields
ride `outcomes[].fields`.

### Parts rendered from fields

An **outcome** maps a `(kind, phase, outcome)` to a reply **`part`**. Every outcome row
carries its `kind`: a phase key can repeat across kinds, so `(kind, key)` is the phase
identity everywhere — in the outcome map, the `expectations` items, and the attach check. A
part is **rendered from the row's `fields`**, never a literal payload:

| `part.kind` | Speaks | Shape |
| - | - | - |
| `text` | a message | `text` (one content-store template id) rendered with the row's `fields`; the platform's renderer resolves the locale from the subject |
| `options` | a message + tappable/link options | `text` (mandatory) plus `options: {field}` (replies from a list field of strings or `{text, description?, id?}` objects) or `{fixed: [{value, label?}], links?}` (each fixed value a reply, unless `links` names it — then a link button whose url is the named field; a fixed `label`, when present, is one content-store template id) |
| `form` | a message + a form | `text` (mandatory) plus `schema_field` (the field holding the answer schema) or a literal `schema`; an optional `values_field` names a field holding an object of top-level property → value that **pre-fills** the form |
| `template` | a rendered provider template | `text` (mandatory) plus `{id, language, params: {<param>: <field>}}` — `language` is the provider template's registered language code (not a locale the template selects) |
| `media` | media (no text required) | `{url_field \| url, kind?}` |
| `talk` | nothing directly | its `fields` become a **fact** handed to the composed-talk slot |
| `carried` | nothing directly | `{phase, outcome}` — its `fields` merge into the named same-intent carrier's render context under `carried.<label>` |
| `none` | nothing | the row is still stamped `sent` |

A part may also declare `repeat_over` (a list field — compose emits ONE part per element, the
element bound as `item` in the render context) and `to` (`user`, the default, or a
party the manifest declares in `parties` — a part sent to a declared party leaves compose as
a **`deliveries`** entry, never in the reply to the user). `fields` lists the fields the part
reads; every field the part names —
`fields`, `field`, `schema_field`, `values_field`, `repeat_over`, a `links` target, a `params`
value, `url_field` — must be a member of the label's `fields`. A form's `values_field` prefill
is forwarded as the platform's per-send form `data.values`; compose refuses loudly (naming the
part and the key) a key that is not a top-level property of the form schema, or a value that
does not satisfy that property's schema — never a silent partial prefill. A client seeds each `part.text` path
through the platform's template-upload door — `POST /api/upload-template` with `{path,
content}` writes the content-store path the part names — the surface the
[stored-content guide](/guides/manage-stored-content) documents.

### The composed-talk slot

`talk_slot` (optional; `null` = off) turns on the composed-talk slot:
`{prompt_ref: <path>, transcript_window_lines}`, where `prompt_ref` is one content-store talk
prompt template id and `transcript_window_lines` (default 10) bounds
the transcript window. When declared, compose runs the talk step after the
fixed parts render, handing it the `talk` facts, the fixed parts, the prior transcript window,
the inbound text, the prompt, and the classifier's `turn_talk` text; it speaks ONE verified
reply appended last (see [the compose step](#the-compose-step)). A `talk`-disposition part with no
`talk_slot` declared is refused at attach.

## The rules the attach check enforces

The template's `declarations.check` is the agenda's structural rule; it runs at attach, names
the first offender, and the attach **refuses** on any message it returns. In an action message
`<via>` is `follow_on.<label>` (a label's follow-on) or `answer.<key>` (an
`expected_input.follow_ons` entry).

| The check refuses when… | Its refusal |
| - | - |
| the mint graph (phase → a label's `follow_on.mint` / `follow_ons.mint` → kind) has a cycle | `mint graph has a cycle through kinds: <kinds>` |
| a sequenced kind declares more than one item | `kind '<kind>': a sequenced kind must be single-item` |
| a `rank` gives both or neither of `ordinal`/`match` | `phase '<phase>' <via>: rank needs exactly one of ordinal/match` |
| a `rank` targets a kind in no sequence group | `phase '<phase>' <via>: rank targets kind '<kind>' which is not in a sequence group` |
| a `rank` `match` key is not a declared field of the target kind | `phase '<phase>' <via>: rank match key '<key>' is not a declared field of kind '<kind>'` |
| a `close` names a static `item` the kind does not declare | `phase '<phase>' <via>: close item '<item>' not declared on kind '<kind>'` |
| a `close` names a static `item` on a kind declaring `item {field}` | `phase '<phase>' <via>: close.item on item-kind '<kind>' — target by item_field` |
| a `mint` names an unknown kind | `phase '<phase>' <via>: mint targets unknown kind '<kind>'` |
| a `reactivate` names a phase key the acting phase's kind does not declare | `phase '<phase>' <via>: reactivate targets unknown phase '<phase>' in kind '<kind>'` |
| a `close` names an unknown kind | `phase '<phase>' <via>: close targets unknown kind '<kind>'` |
| a `close` `outcome` is not a label of EVERY phase of the target kind | `close from '<phase>' needs outcome '<outcome>' on phase '<key>'` |
| a `close` `outcome` names a non-`resolution` label | `close from '<phase>' outcome '<outcome>' must be a resolution label on phase '<key>'` |
| an `item_field` is not a field of its source label | `phase <kind>.<key>: label '<label>' item_field '<field>' is not in the label fields` |
| a kind declares both `item` and `items` | `kind '<kind>': declare one of item or items, not both` |
| an `item.field` is not in the kind's `fields` | `kind '<kind>': item field '<field>' is not declared in fields` |
| a phase kind or key is not id-safe (each heads a phase key) | `phase kind '<kind>' is not id-safe (letters, digits, underscore only)` / `phase key '<key>' …` |
| the same `(kind, key, item)` phase is declared twice | `phase <kind>.<key> item <item> is declared twice` |
| two distinct `(kind, key)` phases collide under the phase-key encoding | `phases <k1>.<p1> and <k2>.<p2> collide under the phase-key encoding` |
| an `ordering_waits` entry is not a `{kind, phase}` object | `ordering wait must be {kind, phase}` |
| an `ordering_waits` entry names an undeclared kind | `ordering wait of phase '<key>' names unknown kind '<kind>'` |
| an `ordering_waits` entry names (non-wildcard) an undeclared phase | `ordering wait of phase '<key>' names unknown phase '<kind>.<phase>'` |
| the `ordering_waits` graph over `(kind, phase)` nodes has a cycle (a self-wait is a length-1 cycle) | `ordering waits form a cycle through <kind.phase …>` |
| the `predecessor` graph within a kind has a cycle | `predecessor chain of kind '<kind>' forms a cycle through <keys>` |
| an `event` input's `event` is blank | `` phase <kind>.<key>: event input needs a non-blank `event` `` |
| an `event` input's `key` is blank | `` phase <kind>.<key>: event input needs a non-blank `key` `` |
| a label declares neither or both of `resolution`/`wait_for` | `phase <kind>.<key>: label '<label>' must declare exactly one of resolution or wait_for` |
| a label's `wait_for` names a `who` that is neither `user` nor `phase` nor a party the manifest declares | `phase <kind>.<key>: label '<label>' waits on '<who>', which is neither 'user' nor 'phase' nor a party declared in \`parties\`\` |
| a `predecessor` object names a label the predecessor phase does not declare | `phase <kind>.<key>: predecessor label '<label>' is not declared on phase '<phase>'` |
| two `outcomes` rows share a `(kind, phase, outcome)` | `duplicate outcome row for <kind>.<phase> <outcome>` |
| an outcome row's `(kind, phase)` names no declared phase | `outcome row names unknown phase <kind>.<phase>` |
| an outcome row names a label the phase does not declare | `outcome row <kind>.<phase> names label '<label>' the phase does not declare` |
| a declared label has other than exactly one map row (full coverage both ways) | `phase <kind>.<key>: label '<label>' has no outcome row` / `… has <n> outcome rows` |
| a part reads a field the label's `fields` omits | `outcome <kind>.<phase> <outcome>: part reads field '<f>' the label does not declare in fields` |
| a part names a field (`options.field`, `schema_field`, `values_field`, `repeat_over`, a `links` target, a `params` value, `media.url_field`) the label's `fields` omits | `outcome <kind>.<phase> <outcome>: part names field '<f>' the label does not declare in fields` |
| an interactive part (`options`/`form`/`template`) carries no non-empty `text` template id | `outcome <kind>.<phase> <outcome>: an interactive part (<kind>) requires a non-empty text template id` |
| a fixed option's `label`, when present, is not a non-empty template id | `outcome <kind>.<phase> <outcome>: fixed option '<value>' label must be a non-empty template id` |
| a part is sent (`to`) to a party that is neither `user` nor one of `parties` | `outcome <kind>.<phase> <outcome>: part is sent to '<to>', which is neither 'user' nor a party declared in \`parties\`\` |
| a `mint` fans out over a source array field into a kind that declares no `item {field}` | `phase <kind>.<key>: label '<label>' mints '<kind>' per element of list field '<field>', so kind '<kind>' must declare item {field}` |
| a `close` names a source array field (a close names ONE item) | `phase <kind>.<key>: label '<label>' closes by list field '<field>', but a close names ONE item` |
| a `carried` part names a target row that does not exist | `outcome <kind>.<phase> <outcome>: carried target <kind>.<phase> <outcome> has no outcome row` |
| a `carried` part names a target that is itself `carried`/`none` | `outcome <kind>.<phase> <outcome>: carried target <phase> <outcome> is itself <kind> (carries no part)` |
| a `talk`-disposition part is declared but `talk_slot` is null | ``label <label> is a talk row but `talk_slot` is null`` |
| the clarify kind lacks a `which` wait label bound to `user` | `clarify kind '<ck>' must declare a 'which' wait label with who 'user'` |
| the clarify kind lacks an `unresolved` label carrying a declared not-done resolution | `clarify kind '<kind>' must declare an 'unresolved' label with a not-done resolution (a resolution other than 'done', from the attach parameter \`resolutions\`)\` |
| the `unmatched_kind` is not a declared intent kind | `the unmatched kind '<uk>' is not a declared intent kind` |
| the `unmatched_kind` declares no phase | `the unmatched kind '<uk>' must declare at least one phase` |
| no phase of the unmatched kind carries a not-done label | `the unmatched kind '<kind>' must declare a phase with a not-done label (a resolution other than 'done', from the attach parameter \`resolutions\`)\` |
| the `unmatched_kind`'s non-empty `sources` does not admit both `event` and `inbound` | `the unmatched kind '<uk>' must admit sources event and inbound` |

The `close` rule spans every phase of the target kind because the target phase is chosen at
run time, so the outcome map must cover the resolution for all of them. The manifest declares
**no** data-fact preconditions, no discard rules, and no thresholds — dueness is computed
from the ledger, never gated on stored values.

The same attach seam also compiles each jq the manifest declares against the template's
schema — a phase's `via` correlation program — and refuses one that does not compile or whose
value type contradicts what the field expects. The cross-state `standing` predicate is NOT
checked here: it reads another state and lives in the client's binding, so the client's flow
validates it against that state.

### Re-attaching over open intents

An attach that replaces the manifest while intents are still open is checked against those open
records too. When an open intent names a kind, a phase, an outcome label, or a part the NEW
manifest no longer declares, the attach is **REFUSED** with `422` and the refusal lists every
orphaned record — the declarations never change under a conversation whose next turn could no
longer resolve:

```
re-attaching template '<template>' on state '<state>' would orphan <N> open record item(s) the
new declarations no longer cover: [<kind>:<key>] <label> (id <id>); … and <N> more. Re-attach
with options {"orphans": "close", "resolution": "<not-done resolution>"} to close them.
```

Open intents whose declarations survive are untouched: their ledger rows, waits, and bindings
cross the attach unchanged.

To retire those declarations anyway, the caller attaches with `options.orphans = "close"` and
names a declared not-done resolution in `options.resolution` (one of the new manifest's
resolution values other than `done`; a name the new declarations do not declare is itself
refused). The attach then **closes** every intent the new manifest no longer covers with that
resolution instead of refusing — set on the intent's open phase rows and marked `closed` on
its ledger row. The close carries no `sent_run`, so it is unspoken: the next mint's prune drops
the intent and compose says nothing for it.

## The parameters

Two attach parameters tune the template without editing its document:

* **`resolutions`** — the enum schema substituted into the `resolution` field at the
  `{"$parameter": "resolutions"}` marker, default `{"enum": ["done", null]}`. `done` is the
  only resolution the engine names; every OTHER member of the enum is a **not-done** name the
  deployment declares here, and a label referencing one closes its intent instead of reaching
  the phase's successors. The template jq read the allowed set as
  `$parameters.resolutions.enum`; a deployment names its own classes (`deferred`, `expired`,
  `declined`) and keeps the wording neutral, so none inherits a business vocabulary.
* **`yes_no_words`** — the bare yes/no word list the mint binds without the classifier,
  default `{"yes": ["yes", "y"], "no": ["no", "n"]}`, read as `$parameters.yes_no_words`.

## The template jq

The agenda's `template_jq` split into two purposes. The **`input`** programs are read-only
predicates over the record subtree — the client's flow reads them through the
[template-jq prelude](/babelfish#the-template-jq-prelude) (`tjq_<name>({…})`) or the record
`GET …/template-jq/{name}` route to decide what is due each pass. `.` is the attached record
subtree; `$declarations` is the manifest, `$parameters` the attach parameters, and a program's
declared `params` ride the single object `$params`. The core predicates read verbatim:

| Program | Params | What it answers |
| - | - | - |
| `reached` | `(phase_key)` | the predecessor is satisfied: a first phase always; a phase-predecessor phase only when that predecessor's current outcome is `done`; a `record`-predecessor phase once the earlier items' same phase is settled in any way; a `{phase, outcomes}` predecessor when the predecessor's current outcome is one of the named labels |
| `pending` | `(phase_key; run)` | `reached ∧ (no current outcome ∨ (reactivated this run ∧ ¬outcome_after_binding) ∨ stale)` — a phase that WANTS to fire this run, ordering aside |
| `stale` | `(phase_key; run)` | the phase's predecessor holds a current outcome that is settled, reaches (the named label for a `{phase, outcomes}` predecessor, a `done` resolution for a bare phase name) and was recorded THIS run, while the phase's own current outcome is from another run or from an earlier pass of this run — a re-settled predecessor makes its successors due again. A `record` predecessor and a phase with no predecessor are never stale |
| `ordering_satisfied` | `(phase_key; run)` | for each `ordering_waits` `{kind, phase}`, no matching phase of ANY open intent of that kind is still `pending` — the acting intent included, the waiting phase itself excluded, `phase: "*"` matching every phase of the kind; a settled/waiting/never-reached target satisfies, only a reached-but-unfired one blocks |
| `phase_due` | `(phase_key; run)` | `pending ∧ ordering_satisfied` — the branch condition a pass fires on |
| `active` | `(id; run)` | an intent minted this run ∨ with any pending phase ∨ with any phase bound this run — reads `pending`, never `due`, so ordering never masks an intent inactive |
| `item_of` | `(id)` | the intent's `item` identity, or `null` for an itemless kind |

The rest of the 56 input programs: `answer_target`, `answered`, `anything_due`, `bound`,
`clarify_rows`, `clarify_step`, `close_targets`, `closed`, `complete`, `compose`,
`current_outcome`, `deadlocked`, `done_outcome`, `due`, `due_set`, `expectations`,
`fill_target`, `follow_on_instances`, `group_of`, `has_open_phase`, `intent_has_inbound`,
`intent_row`, `intent_user_wait`, `intent_wordless`, `items_of`, `key_parts`,
`manifest_phase`, `open_clarify`, `open_intents`, `open_option_expectations`,
`open_yes_no_expectation`, `outcome_after_binding`, `pending_follow_ons`, `placed`,
`rank_targets`, `reactivated`, `reply_safe`, `resolve`, `settled`, `settled_this_run`,
`turn_source`, `unresolved_class`, `via`, `waiting`, `wordless_conflict`, and the graph
helpers the attach check reads to refuse cycles (`mint_adjacency`, `ow_adjacency`,
`seq_edges`, `reachable_cyclic`).

`due_set` orders the due items by intent `rank`, ties by the total mint order, one grouped
intent per pass; `expectations` returns the open waits `[{key, kind, phase, outcome, who,
expected_input, fields, question_ref, schema_field, schema, options}]`, the `expected_input`
joined from the manifest phase (the wait row carries only `wait_for` and `fields`), the
`schema_field`/`options` read from the outcome map's part — so the mint binds a form re-entry
by the row's own schema (`fields[schema_field].required`) and an option tap by the row's own
candidates, never by a static phase schema. `pending_follow_ons` reads the same `placed`
predicate the seed writes against, so the pair never disagrees — a branch never fires over an
empty slice, and the loop never over-runs a placed follow-on.

`complete` asserts every reached phase has settled or is waiting, and it holds wherever the
loop stops, because the attach check keeps each kind's `ordering_waits`, `predecessor`, and
mint graphs acyclic. At loop end nothing is pending, or the loop would not have stopped; a
reached phase that is neither settled nor waiting would be pending but ordering-blocked, so
its blocker is a pending same-kind phase, whose blocker is another pending phase, and so on —
a chain that, over an acyclic wait graph, must end at a pending, ordering-satisfied phase,
which is due. That contradicts the loop having stopped, so `complete` failing is a real bug —
a handler that fired without recording an outcome — never a benign ordering stall.

The `stale` disjunct re-opens settled phases, and it terminates for the same reason: a stale
phase stops being stale once it re-records at a pass at or after its predecessor's, each
re-record stamps a pass no earlier than the predecessor's, and the predecessor graph is a DAG
(the attach check refuses a cycle), so the re-reach cascade runs down finitely many edges. A
settled phase whose predecessor was re-settled this run is therefore due, not `complete`'s
business: `complete` stays true over it while the loop keeps going, exactly as it does over a
reactivated open wait.

### The update programs

The **`update`** template jq write the ledger. Each reads the current subtree as `.` and the
value the [binding adapter](/babelfish#binding-a-node-to-a-state) shaped from the node's output
as `$input` — and returns a template-relative op batch under the writer
regimes; the record `POST …/template-jq/{name}` route (or a node binding's update) applies it.
The five are:

* **`mint`** — turns each inbound into records or binds it to an open expectation WITHOUT
  language judgment (`writes` `ledger`, `ledger_phases`, `ledger_inbound`). It mints standing
  intents whose predicate holds, binds an `event` turn by `expected_input.event` and its `via`
  to the waiting phase whose item matches, binds a `form` submission by its own row schema,
  binds a tapped `option` by its own row candidates, and binds a bare yes/no (via
  `yes_no_words`, no classifier call) when exactly one `open_yes_no_expectation` is open. An
  event with zero or several hits, or a form with no hit, mints an
  [`unmatched_kind`](#how-re-entry-binds) record; a form with several hits opens a clarify. It
  also **prunes** intents already closed and no longer referenced, and computes the open
  expectations the classifier reads.
* **`record`** — takes the classifier's structured `verdict` (or null) and writes per-kind
  spans as `ledger` records (`source` from `turn_source`, `item` from the kind's `item {field}` when declared), `answers` bindings as `ledger_inbound` rows, and each `ambiguous`
  span as a clarify — re-binding an already-open clarify and climbing its `attempt` up to
  `clarify_limit`, at which point it records the `unresolved` label (`writes` `ledger`,
  `ledger_phases`, `ledger_inbound`, `turn_talk`). With a `talk_slot` declared and a non-blank
  `verdict.talk`, it is the sole writer of `turn_talk`. Before it writes a row it refuses two
  bindings that resolve to one phase key in one pass
  (`agenda: two bindings resolve to phase <key> in one pass; a phase is answered once per pass,
  never twice`) and an ambiguous binding naming fewer than two candidates
  (`agenda: ambiguous binding on <span> names <n> candidate(s); ambiguous needs two or more` —
  the classifier contract, not the template, guarantees an ambiguity has options to choose
  between).
* **`seed`** — runs every pass; re-evaluates standing conditions and places pending follow-ons
  by one **match-else-mint** rule (bind to the open intent's waiting phase, else its next
  reached-unsettled phase, else mint a new record — never a closed intent) (`writes` `ledger`,
  `ledger_phases`, `ledger_inbound`). Follow-ons come from a wait's answer and from each label
  (resolution OR wait) recorded this run, read as `label.follow_on`. A `close` writes the
  target's open phase a full outcome row visible to `due` in the SAME pass; a `rank` is a
  `merge_by_key` on the target `ledger` row. Every action is bounded by the shared `placed`
  predicate — one placement per instance — and, before it writes a row, seed refuses two
  follow-ons that resolve to one phase key or to one intent id in a pass
  (`agenda: two follow-ons resolve to phase <key> in one pass; …` /
  `agenda: two follow-ons resolve to intent <id> in one pass; …`).
* **`outcome`** — validates each phase's returned `{key, outcome, fields, waits_on?}` (the
  `key` is due this pass; the `outcome` names a label the fired phase declares; every `fields`
  key is one the label lists; a `resolution` label's derived class is among the attached
  `resolutions`; a `wait_for` label's derived party is `user`, `phase`, or one of the
  manifest's declared `parties`; a `who: "phase"` label requires `waits_on`) and writes one
  `ledger_phases` row per outcome — the class and party read from the declaration, never the
  handler (`writes` `ledger_phases`). Two results carrying one key are refused before a row is
  written (`agenda: two results resolve to phase <key> in one pass; …`). A breach raises loudly.
* **`compose_mark`** — after the pass loop, writes the `closed` mark on every fully-settled
  intent, the `sent` run stamp on each rendered row, `last_outbound` `{run}` when the turn
  speaks, and the `transcript` window (`writes` `ledger`, `ledger_phases`, `transcript`,
  `last_outbound`). See [the compose step](#the-compose-step).

`reconcile` is the template's own three-program set (`orphans`, `close`, `resolutions`) the
platform runs when a [re-attach](#re-attaching-over-open-intents) retires declarations over
open records.

## The compose step

Compose runs after the pass loop, reading the rows the outcome update committed. The `compose`
input program first asserts `complete($run)`, else the flow raises
`agenda: incomplete run: <intents>` (the open intents' ids) — which becomes the route's error
reply. Then, for each row of `settled_this_run` and each open wait whose question has not yet
been `sent`, it
resolves the outcome map's part — keyed `(kind, phase, outcome)` — and renders it **from the
row's `fields`**:

* **`text`** renders through `render_text` over the part's content-store template id, the
  row's `fields` as the render context, and the platform's renderer resolves the locale from the
  subject — the template selects no language variant. A `text` that is not a template id string
  raises `agenda: part text for phase <key> is not a template id` rather than sending an empty
  message.
* **`options`**, **`form`**, **`template`**, **`media`** build their surfaces from the same
  fields — `options` from a list field or the fixed values, `form` from `fields[schema_field]`,
  `template`/`media` from their named fields. A `repeat_over` part fans out to one part per
  element of the named list field, the element bound as `item`.
* **`talk`** hands its fields to the talk slot as a fact and speaks no part; **`carried`**
  merges its fields into the named same-intent carrier; **`none`** speaks nothing but is still
  stamped `sent`. A carried row whose carrier is not spoken this turn raises
  `agenda: carried row <label> has no carrier this run` — unless the row is an open wait and
  the carrier's current outcome is the label the part names and already carries a `sent`
  stamp, in which case the question stands as already asked: the row sends nothing, renders no
  unit, and is stamped `sent` this run. (A reactivation re-records an open wait and drops its
  `sent` stamp, so compose meets the wait again while its carrier stays unsent.)
* a **`to`** naming a declared party routes the part into **`deliveries`** — a list of
  `{to, part}` the client's own `send` nodes deliver — instead of the reply to the user.

A part whose `fields` names a field the row does not carry raises
`agenda: part <kind>.<phase> <outcome> needs field '<f>' the row does not carry`, and an
outcome with no matching map row raises `agenda: no part for <kind>.<phase> <outcome>`
**before** any closed mark, so an unmapped outcome never silently closes its intent.

**The talk slot.** When the template declares a `talk_slot` and either a `talk` fact was handed
or the classifier supplied `turn_talk` text, the talk step runs after the fixed
parts render, and its one verified reply appends **last**. The classifier's talk is an INPUT
to the slot, never spoken as a part directly, and when the slot is declared but no fact and no
classifier talk exists, no talk part is emitted. The slot's `check` enforces two fatal
rules and one non-fatal one:

1. every handed fact leaf must appear in the text, else
   `agenda-talk: fact <label>.<field> not spoken` (fatal);
2. every id-shaped token (`[A-Z][A-Z0-9]*-[0-9]+`, e.g. `A-42`) must trace to a handed source
   — a fact, a fixed part, a transcript line, or the inbound — else
   `agenda-talk: text carries '<tok>', which was not handed` (fatal);
3. every bare numeric token not found in those sources is NON-FATAL — collected on
   `unverified_numbers` (visible in the run record's node output) so ordinary prose numbers
   ("two options", "in 5 minutes") never fail a turn.

`compose` returns `{parts, deliveries}` — `parts` the ordered `AnswerPart[]` the route returns
as its reply, `deliveries` the other-party parts. The `compose_mark` update then writes the
`closed` mark on every fully-settled intent, the `sent` run stamp on each rendered row (the
guard that sends a wait's question exactly once, never re-asking an open wait whose question
already went out), `last_outbound` `{run}` whenever this turn speaks (a silent turn re-emits
the prior pointer), and the `transcript` window (written after the talk, so the stored outbound
line includes the talk text).

## Using the agenda from a flow

A client attaches the agenda template to a state and drives it from one flow, wiring the pieces
the template does not itself run: a classifier, the pass loop, and the reply. There is no
shipped node, no lowering, and no chips — the template is data, and the flow orchestrates it
through [per-node bindings](/babelfish#binding-a-node-to-a-state) and the
[template-jq prelude](/babelfish#the-template-jq-prelude):

* **mint** — the flow applies the `mint` update at the start of the turn (input injections
  read the open `expectations` and `turn_source`), turning the inbound into records or binding
  it to an open expectation.
* **classify** — the flow's own classifier node (a `tools_agent`) runs once over the inbound
  when the mint left spans to classify; its forced response schema and prompt are built by jq
  from the manifest's intents. The flow applies the `record` update over the verdict.
* **the pass loop** — a [Router](/babelfish#routing-on-a-verdict) in
  [Loop](/babelfish#dispatch-once-or-loop) mode runs the passes: each pass applies the `seed`
  update, reads `due_set`/`anything_due` (the loop's stop condition) through the prelude,
  dispatches each due item to the flow's handler for that intent — one run per due item, an
  unsequenced kind in parallel, a sequenced kind one at a time in rank order — and applies the
  `outcome` update over each handler's `{key, outcome, fields, waits_on?}`.
* **compose** — once the loop stops, the flow reads the `compose` input program for the reply
  and applies the `compose_mark` update; the route returns `.parts` and feeds `deliveries` to
  its own `send` nodes.

Because the agenda is a state template, it appears on the platform
[States screen](/studio/screens#states): it lists among the state-template documents, and a
client attaches it to a state and edits the attachment's `declarations` there — its manifest.

A handler for an intent reads the due item — its `{key, intent, item, kind, phase, rank,
fields}` — from the pass, does its work through the flow's own tools or a published flow, and
returns `{key, outcome, fields, waits_on?}` where `outcome` is a label the fired phase declares
and `waits_on` is supplied only for a `who: "phase"` wait. The handler reads state only through
the flow's own bindings and never writes the agenda ledger directly — the flow's `outcome`
update records the returned label, deriving the class and party from the declaration.

## The pass-loop rules

* **No asks inside the pass loop.** A handler never contains an `ask` or any interactive
  preset: a parking ask inside a fan-out re-runs its siblings on resume. An outbound question
  is a `wait_for` label the handler returns, spoken by compose — never a mid-loop prompt.
* **No preconditions on data facts.** Dueness comes only from the phase graph and the
  ledger's outcomes and bindings; the manifest declares no thresholds or stored-value gates.
* **A hit cap is a bug.** The loop's max-runs cap (default **20**) is the backstop, not a
  conversation state: reaching it raises, and the failure travels the flow's ordinary
  [`on_error`](/babelfish#handling-a-nodes-error) path. The template computes no static pass
  bound and the manifest declares none; what makes the loop finite is the attach check's
  refusal of a cycle in the `predecessor`, `ordering_waits` and mint graphs, plus the rule
  that a fired phase records an outcome and so stops being due. The cap on the client's loop
  must be generous enough for the manifest's longest predecessor/ordering-wait chain, which
  the client sizes from its own declarations.

## How re-entry binds

No outbound part carries a correlation key (`AnswerPart` forbids extras), so a later inbound
binds to an open wait by MATCH, and the `mint` update does it without the classifier:

* an **event** binds to the waiting phase whose `expected_input.event` names the event's kind
  and whose `via` (a jq program compiled over the flow root, `$key` bound to the payload's
  `key` field; absent means the `key` value itself) resolves to the wait's item — the ledger
  row's item for a one-per-item kind (`item_of`), else the phase key's item segment, else the
  intent id. The [event door](/reference/conversation-bridge#the-event-door) delivers it as a
  turn, and a payload missing that `key` raises `agenda: event <kind> carries no '<key>'`. An
  event with **zero or several** matching waits binds nothing and instead mints one
  `unmatched_kind` record; a malformed event (no `id`/`kind`) raises
  `agenda: malformed event turn — an event carries an id and a kind`.
* a **form** submission binds to the open form-wait whose ROW-carried schema's required
  properties are all present; **several** matches open a `clarify_kind` intent, **no** match
  mints an `unmatched_kind` record carrying the form payload;
* a tapped **option** arrives as the option's value in the message and binds to the single
  open option-wait whose ROW candidates hold that value;
* a bare **yes/no** binds when exactly one yes/no wait was asked in the **last outbound** line
  — the mint matches it against `open_yes_no_expectation`, so a yes/no never lands on a
  question two turns old.

**The unmatched kind.** An event that matches no wait (or several), and a form that matches
none, mints one record of the manifest's `unmatched_kind` (default `unmatched`) —
`{kind, source, event: <payload>, fields: {reason, candidates, inbound_kind}, rank,
minted_run}`, `reason` `no_match` (zero) or `ambiguous` (several), `candidates` the hit phase
keys. It reaches its own phase and is resolved by that kind's handler (a `done` or a declared
not-done resolution) like any other intent, and compose speaks its part. The record bypasses
the record update's `sources` gate, so the check enforces the unmatched kind's admission statically (its `sources`
must be absent/empty or cover both `event` and `inbound`); the mint never consults `sources`
at run time.

**Wait parties.** A wait's `who` is `user`, `phase`, or a party the manifest declares in its
`parties` list and the label names. `user` and `phase` are the engine's own. The classifier
binds a span only to a `user` wait — the platform-owned expectations instruction tells the
model so, and every expectation item carries its `who`. A declared party is held for someone
off this conversation: its wait wakes on an event of its declared kind delivered through the
[event door](/reference/conversation-bridge#the-event-door) (whatever posts that event is a
deployment-side adapter). A `phase` wait resolves internally when the phase its handler named
in `waits_on` records a resolution.

## Termination

The loop always terminates. `due` excludes a phase with an outcome after its latest binding
this run, and every fired handler records an outcome (the compose assertion catches one that
did not), so a phase never re-fires. A phase-predecessor chain ends the moment a phase
resolves to anything other than `done`: a not-done resolution leaves every phase successor
unreached, so the intent runs out of open phases and compose closes it, speaking that
terminal resolution. Item order under a `record` predecessor is the exception — it advances on
any resolution of the earlier items, so a not-done resolution on one item never drops the
items that follow.

Cross-intent waits are a **DAG** over `(kind, phase)`: the attach check refuses a cycle in the
`ordering_waits` graph, the `predecessor` graph within a kind, and the mint graph, so a chain
of waits always bottoms out in a due phase and a fresh intent can never be minted every pass.
Re-activations, closes, and ranks are each bounded by the `placed` predicate — one placement
per instance, an empty target set counting as placed — so a settled-first target never keeps
the loop alive. A **closed** intent is never re-opened, and it is pruned once no open intent
still names one of its phases. The pass cap is the backstop, and hitting it is a manifest bug.


# Babelfish
Source: https://docs.tai42.ai/babelfish/index

The paid deterministic-flow product family built on the open platform: what it is and how it plugs in.

Babelfish is TAI42's paid product family for teams that need agent work to run
deterministically in production. It is built on the same open platform this site
documents, and it reaches a running server the same way any other plugin does.

> [!NOTE]
>
> Babelfish is proprietary and licensed commercially — it is not part of the
> Apache-2.0 platform and is not published to PyPI or listed in the
> [marketplace](/concepts/marketplace). Product details and pricing live at
> [tai42.ai/babelfish](https://tai42.ai/babelfish).

## What it adds

Babelfish Flows ships as one installable plugin carrying two halves:

* **A flow engine.** Deterministic flows registered as ordinary
  [tools](/concepts/tools-and-extensions) through the public contract — run a
  flow, step it, read its state, and abort it. Because they are tools, everything
  the platform already does to a tool applies: access control, backends,
  schedules, and tracing. Aborting a flow parked on an async ask while an answer to
  it is being driven does not cut that drive short: the abort is **requested** of it
  (`flow_abort` reports `found: true` with `mode: "requested"`) and the drive honours it.
  Only such a requested abort waits for the live drive; an abort reported
  `found: false` lapses within 60 seconds and never aborts a later resume.
* **A flow editor in the Studio.** A front-end bundle the runtime serves to the
  [Studio](/studio) through its integrity-pinned import map, contributing a
  top-level **Babelfish Flows** page and its sidebar entry; the states a flow binds
  live on the platform [States screen](/studio/screens#states). On the canvas, nodes can be gathered
  into named, collapsible groups — a collapsed group renders as one card that hides
  its members and reroutes their boundary edges, and expanding it reveals them
  again. Groups persist with the flow and carry across the editable, run,
  read-only history, and reading views, showing an aggregated member status in Run
  mode; the collapse/expand toggle itself is a transient view preference and is not
  saved.

A saved flow is a versioned [preset](/concepts/presets) with the graph carried in
the preset's fixed arguments, so flows version, diff, and roll back through the
[versioning spine](/concepts/versioning-spine) like everything else.

## The explanation layer

A flow carries an explanation layer aimed at the person reading it, not just the
engine running it. Nodes and flows take plain-language descriptions, the editor
renders a generated legend that summarizes what a flow does and the pieces it uses,
and a dedicated reading view presents the whole flow as an annotated walkthrough — a
calm, non-editable mode for reviewing or explaining a flow without changing it.

## Presets

Beyond the built-in steps, you can define your own palette nodes from saved flows:
promote a flow into a reusable node, give it a category and an icon, and it appears
in the editor's palette alongside the defaults for anyone to drop into a new flow.

Babelfish ships two ready-made interaction nodes to start from — **`send_node`** and
**`ask_node`** — one full surface each, covering the common conversation moves out of
the box. **Send** delivers one-way and **never waits**: a text message, display
**media** (a list of `{kind: image | link, url, caption?}` items), tappable
**options**, a pre-approved **template**, or a fillable form **schema** delivering
a schema-rendered [ask-less form](/concepts/notifications#ask-less-forms) — the
outcome is `sent` or `failed`, and a form's submission, if it comes, arrives as the
person's next message on the conversation route. A send form takes the same two
per-send extras an ask form does — `data` to open it already filled in and `pages`
to split it into ordered steps — layered over the schema for that one send. Its face opens on a **kind**
selector — message, media, options, template, or form — that guides the fields
while the node stays one delivery whatever the face: `kind` is face-only and never
delivered, every send carries a message or media, and one message carries one
interactive surface (a template stands alone). **Ask** pauses for a person's reply
and **always waits**, re-asking until the answer is valid or the attempts run out;
its **format** selects how the answer is collected — `text` (free text, with
optional `options` as tap-to-send suggested replies), `confirm` (a yes/no —
declining is an answer), `select` (one pick from `options`), `form` (an answer
validated against `schema`), or `external` (an action completed on a surface
reached through `link`, with the callback payload as the answer) — and the same
format drives the face's variant picker. An answered ask ends `{outcome: "answered",
answer, reply_to, params}`: `reply_to` is the message the answering reply quoted
(`{message_id, status, text}`, `status` one of `found`, `not_found`, `sensitive` or
`no_text`; `null` when the reply quoted nothing or did not come over a channel), and
`params` the string values the channel sent beside the answer (`null` when none). See
[replies to an earlier
message](/reference/conversation-bridge#replies-to-an-earlier-message). A `form` ask also takes two per-send extras
layered over the schema for ONE send — the same
[`data` and `pages`](/concepts/interactions#prefilling-per-send-options-and-pages)
the platform's ask surface carries: `data.values` prefills top-level properties (each
shown filled in and validated), `data.options` supplies a per-send choice list that
replaces a string property's `enum` for this send, and `pages` splits the form into
ordered titled steps (every property appearing exactly once; absent `pages` is one
page). Both forward to the ask door only when set, validated against the form's schema. Both nodes take optional display media
beside their prompt, every optional field is inert when omitted, and field
combinations richer than any single face stay expressible through each node's
full-surface **Anything** face.

**Addressing is pre-wired to the conversation.** A freshly dropped send or ask node
opens already addressed to the same channel and counterpart the flow's conversation
runs on — so one flow works across every channel and always reaches the person of the
current conversation. The wiring is a **visible, editable jq expression** seeded into
the node's addressing slot (through the [visual jq editor](#the-visual-jq-editor)),
never a hidden default: it reads the participant's own `{channel, sender}` off the
conversation-routed flow's inputs, and the node's own literal addressing merges under
it. Off a conversation route those inputs are absent, and the expression is written to
drop its empty values, so it **contributes nothing** — the node falls back to whatever
you address it to by hand. A reply that rides the route itself needs no addressing at
all.

A conversation-routed flow also reads **`.flow_graph_kwargs.turn`** — the turn the
inbound entered as, surfaced on every conversation turn as `{id, inbound: {id, kind,
source}}`. `turn.id` is the turn's stable id (the answer record's id); `turn.inbound`
describes the entry — `inbound.kind` is `"message"` or `"event"`, `inbound.id` is the
channel provider message id, the event id, or the api record id, and `inbound.source`
is the channel name, `event:<kind>`, or `api`. An [event
turn](/reference/conversation-bridge#the-event-door) additionally carries
`.flow_graph_kwargs.event` (`{id, kind, payload}`) with `.flow_graph_kwargs.message`
and `.sender` both `null`. These arrive under `flow_graph_kwargs` because the
conversation route's default no-`start_expr` kwargs are `{message, sender, turn}`
(plus `event` on an event turn); a route with its own `start_expr` reads `.turn` and
`.event` on the payload and forwards what it wants. A conversation-target flow preset
must not declare `additionalProperties: false` without admitting `turn` (and `event`)
in its input schema, or the routing that validates the kwargs against the preset's
input schema refuses them.

A preset is a saved flow published to the palette, and it is managed **as a
node, not as a flow**. The palette's Presets section gives each card an edit
control that opens its flow editor and a delete control that raises a guarded
confirm, and a **+ New preset** action starts a fresh one in place. Deletion
routes through ordinary [preset](/concepts/presets) deletion, so it unregisters the
tool; the confirm states the blast radius plainly — the node leaves the palette, and
any flow that already embeds it keeps a now-dangling reference to it. A preset
lives in the palette **only**: the flows list shows flows, never presets — nor a
category folder emptied by them — so a palette-managed node never surfaces among your
standalone flows.

## Looping over a list

The **map** node is a first-class "friendly foreach": it runs one tool over a list.
Its face is a list `input` (a jq expression producing the items), the mapped tool,
per-item keyword arguments (jq expressions that may read the current item and its
zero-based index through `$iterate.item` and `$iterate.iteration`), and the
producer nodes whose outputs those expressions may read. It runs either
`sequential` or `parallel`, with an optional concurrency cap on the parallel mode,
and an optional `collect` expression that shapes the mapped results — left unset,
downstream reads the raw per-item output list directly.

A map compiles down to the engine's ordinary loop primitive: on save it becomes one
loop node plus one body, and on load that marked cluster folds back into the single
map node, so you never touch the mechanism. A loop authored by hand carries no such
marker, is never folded into a map, and stays a visible Loop.

Because a map *is* a loop on the wire, its entry is a barrier: the map face carries
the same dispatch controls a hand-authored loop does — the [wait mode and the
give-up pair](#node-waits), and the opt-in [state refresh](#refresh-opt-in-state-re-read),
which fires **once at loop entry** so every iteration inherits the same fresh view.

**Broadcast** is the map-plus-send recipe for fanning one message out to N
recipients: make the mapped tool the **send** node, set `input` to the
recipients list, and read the current recipient from `$iterate.item` in the
per-item arguments. The per-item output list is the delivery transcript — one slot
per recipient, in order — and because send recovers a failed delivery into
a `failed` outcome in-body, a partial failure simply appears as failed slots in that
transcript rather than aborting the whole map. Scale a large list with the parallel
mode and a concurrency cap, and shape a sent/failed summary with `collect`.

## How a run runs: tool calls, loops and abort

In autopilot a node awaits a tool that does not declare `tai42/pauses` inside the node;
the run pauses only at a declared pausing tool or a holder. A node keeps the pause — its
tool call becomes a pause the run resumes from — when its own tool can pause (a flow call,
an async ask, any [tool that can pause](/guides/build-a-tool#tools-that-can-pause)), when
its On Error handler tool can pause, or, inside a loop body, when any tool of the body (its
On Error handlers and nested bodies included) can pause or the body holds a holder. A
stepped run (`flow_step`) pauses at every tool call, since its caller runs the tools.

`config.max_iterations` (default 100) is the ceiling on the loop rounds a flow may run:
the items or rounds an iterate may plan, a `while` loop's default cap, and the bound a
node's own cap or a router's `maxRuns` must stay under. The engine bounds the graph steps
one run segment may take from these caps; a flow within its caps never meets that bound.
There is no setting for it.

`config.checkpoint_retention` declares how long this flow's run memory is kept, in minutes:
`waiting_minutes` while a run may still continue (a pause), `finished_minutes` after it
reached its terminal. Either may be left out: an unset waiting is the platform's, an unset
finished is the platform's capped at the waiting. Both are bounded by the platform's two
[retention values](/operate/checkpoints#a-threads-own-retention): a flow may shorten them,
never lengthen them. An empty object, a value that is not a positive whole number, or a
finished value longer than the waiting one is refused wherever the flow is parsed; a value
above the platform's is refused by the editor's save gate and by every run and query of the
flow, before any node runs, naming both values. Every checkpoint of the run — the top level,
every loop body, every pending write — is kept that long, and an async ask's deadline must fit
the declared waiting less the redelivery horizon, as it fits the platform's (see
[Checkpoint retention and durability](#checkpoint-retention-and-durability)). A child flow a
node calls declares its own; the parent's never crosses the call. The [agent session threads](#agent-session-continuity) a run owns keep the
platform's waiting retention and take the flow's finished retention at the run's terminal.

```json theme={null}
{"config": {"entry_points": ["fetch"], "checkpoint_retention": {"waiting_minutes": 10, "finished_minutes": 5}}}
```

In the editor the declaration is the Start node's "Checkpoint retention (this flow)" group
(the Sub-Flow Start form carries the same group for a sub-flow). Empty inputs keep the
platform's values; the form itself refuses a finished run longer than the waiting run, and the
save gate's banner carries the engine's refusal of a value above the platform's.

![The Checkpoint retention (this flow) group on the Start form: its description, and the Waiting run and Finished run minute inputs, both empty with the placeholder platform.](https://mintcdn.com/tai42/GIUznzIs4DR40qfu/images/studio/checkpoint-retention-empty-light.png?fit=max\&auto=format\&n=GIUznzIs4DR40qfu\&q=85\&s=95023303fcf4fda843fec2fd272cc3d6)

The Start form's checkpoint retention group with nothing declared.

![The same group with Waiting run 5 and Finished run 6, and the error Finished run must not exceed waiting run under it.](https://mintcdn.com/tai42/C97bEX4Y1-MJSgdV/images/studio/checkpoint-retention-error-light.png?fit=max\&auto=format\&n=C97bEX4Y1-MJSgdV\&q=85\&s=59f46fe227933e02d062f890dad3c0e7)

A finished run longer than the waiting run, refused by the form.

![The flow editor after Save: the banner The engine rejected the flow: with the line checkpoint retention waiting\_minutes (20000 min) exceeds the platform's 10080 min (LLM\_PROVIDER\_CHECKPOINT\_RETENTION\_WAITING\_MINUTES).](https://mintcdn.com/tai42/C97bEX4Y1-MJSgdV/images/studio/checkpoint-retention-refused-light.png?fit=max\&auto=format\&n=C97bEX4Y1-MJSgdV\&q=85\&s=8a03da173f8a7069b69474386cf43c01)

A save refused by the engine: the waiting run is above the platform's.

A loop is an iterate node: a cycle of edges, conditional branch paths, holder ask exits
(`on_ask`) or the route from a holder with an ask exit to a conditional that lists it in
`inputs` is refused at validation.

A cooperative `flow_abort` stops the run before or after a node's tool call, or between
graph invocations; a running tool call finishes first (`hard=True` cancels it). The abort
reaches every worker by event, and a worker that misses the event still sees the request
within 20 seconds.

A tool that returns a park signal without declaring `tai42/pauses` fails its node: a node
failure of source `app` the node's On Error sees, with `.upstream_outputs.error_type`
`UndeclaredPauseError`, `.upstream_outputs.error_kind` `unknown`, and the tool named in
the message. Inside a loop body it is a failed iteration like any body node failure, and a
run it fails runs the flow-level On Error.

## Inputs and results

Each flow declares its own inputs and results — the values it expects when it starts
and the values it hands back when it finishes — so a flow presents a clear contract
to whatever calls it and the editor can prompt for the right inputs when you run one.
Because a flow is a [tool](/concepts/tools-and-extensions), a parent flow can invoke
another flow as a subflow through that same contract.

A node's declared inputs are only part of what it receives: an edge into a node adds
the producing node's output to the node's input, so a node often receives more than it
declares (a fan-in [waits on](#node-waits) every declared **or edge-derived** input).
The **`flow_resolved_inputs`** authoring tool makes that explicit — given a flow graph
it returns, per node, both its **declared** inputs and the inputs the engine
**resolves** it to actually receive at run time, the declared ones plus the edge-derived
ones. It reads the graph passed to it — a held flow is its own graph — and computes
without building, compiling, or running anything, so it is reachable like any other
authoring tool (`validate_flow`, `validate_binding`, `read_flow`) through
[run-tool](/studio/running-tools). The Studio's flow editor reads it to draw a node's
[Receives from block](/babelfish/studio#the-node-edit-panel).

A subflow also **joins the dispatching run's trace** rather than minting a separate
one, and so does an agent a node drives — see [one run, one
trace](/operate/observe#one-run-one-trace). The join survives parking, including a
completing child cascading into its parked parent.

Every flow jq also binds **`$run`** — the executor's identity for the run the
expression evaluates in — as `{id, epoch}`. `$run.id` is the run's session id (the
run registry key), so a flow-as-tool subflow reads a **distinct** `$run.id` from its
parent — the sub-run's own id. `$run.epoch` is the state-mint epoch, `null` on a
stateless run and until the run's stateful mint has run. Outside a run — a
validation-time compile — `$run` is `null`.

> [!WARNING]
>
> A subflow's state writes are invisible to a later parent node unless that node opts
> in. A run's `$states` view is its snapshot from run start plus its own writes: a
> subflow's writes land on the shared record immediately, but a later parent node folds
> them in only if it sets [refresh state](#refresh-opt-in-state-re-read). Without it the
> parent keeps reading its mint-time snapshot — a silent stale read.
>
> A subflow reads only the states **it** is bound to, fresh at its own start; an
> unbound `$states.<name>` reads as **null** — bind it, or the `state_unbound` lint
> flags it. The lint runs per subflow against **that subflow's own** bindings — a state
> the parent binds never masks a read the subflow makes unbound — and its findings carry
> the subflow's path into the Studio problems panel like the parent's.

## Calling another flow: cancel, resume, start

A node that starts, resumes, and cancels a **parkable call** — a **Flow Call**, a
**custom node** (a saved flow published to the palette), or an **agent** — is a
**holder**. On the wire its `type` is `"holder"`, it holds a saved flow or any registered
agent — or a preset over one — (the `tool` / `tool_kwargs` pair), and the runtime decides
which of the two the call is by resolving `tool`, never a second field. A holder has no plain expression input;
instead it carries jq slots evaluated over the [node
envelope](/babelfish/jq-editor#what-each-field-seeds) with the held call's parked
interactions bound as `$parked`:

* **`start_expr`** — shapes the held call's start input. Absent starts the held target
  on the resolved node input; a jq giving null starts nothing; any other result **merges
  over the resolved node input** (a non-dict result wrapped as `{input: …}`), the
  expression's keys winning on collision.
* **`cancel_expr`** — null, one parked-ask id, or a list of ids to cancel; a cancel
  tears the whole held chain down.
* **`resume_expr`** — a list of rows, one per ask of a step. Each row's `id_expr` names
  the parked ask to resume and an optional `payload_expr` carries the answer; an absent
  payload **takes** the ask's own default answer, a payload giving null resumes with
  null.
* **`warmstart_expr`** — the [warm-start](#warm-start) rows a Flow Call pre-fills its
  held flow's nodes with.
* **`on_ask`** and **`send_up`** — where a caller ask goes (see [the ask
  exit](#the-ask-exit-and-sending-an-ask-up)).

When none of a holder's expressions reference `$parked`, the engine does not fetch
the held call's parked list before running them.

**A parking target must be a holder.** A saved flow parks, and an agent parks when its kind
declares that it can (the platform's agent registry says so for each registered agent). A
plain runnable that calls a parking agent, or a preset over one, is refused at validation:
`Node '<id>': agent '<agent>' can park, so it must be a 'holder' node, not a plain runnable.`
(for a preset: `Node '<id>': tool '<preset>' is a preset over agent '<agent>', which can park,
so it must be a 'holder' node, not a plain runnable.`). An agent that does not park may be
called by a plain runnable or held. A held agent **can ask its caller** when it parks and its
static tool set — the kind's own fixed tools, a preset's saved `tool_names`, and the holder's
own `tool_kwargs.tool_names` — names the `ask` tool.

A held call that **fails** — an agent whose resumed run raised (a model or provider error,
say), or one whose resume the platform gave up on — reaches the holder as a failure, never
as a result: the holder fails, so its [On Error](#handling-a-nodes-error) runs, or the flow
fails when none is set.

The [holder panel](/babelfish/studio#the-holder-panel) in the editor authors these
slots; a [hand-authored outcome](/babelfish/wire-form) routes the held call's result
the same way the editor's chips do.

![The holder node's edit panel: the Cancel, Resume and Start expressions and the send-up switch.](https://mintcdn.com/tai42/C97bEX4Y1-MJSgdV/images/studio/holder-panel-light.png?fit=max\&auto=format\&n=C97bEX4Y1-MJSgdV\&q=85\&s=8d2090f2993413e7c5e74f4655d319a0)

The holder node's edit panel: the Cancel, Resume and Start expressions and the send-up switch.

## The ask exit and sending an ask up

When a holder's held call **can ask its caller**, those asks need somewhere to go, and
the holder settles that two ways:

* **An ask exit (`on_ask`).** Name a node in the flow as the ask exit and the holder
  routes to it when the held call settles with asks; its other outcomes take the
  ordinary edges. The card grows an extra **ask** exit handle, and wiring it is required
  — an unwired exit is a save error on a holder that can ask. The exit settles the held
  call's caller asks itself and does not re-park on them: taking it **releases** the
  held run, which stays parked on its own ask, standalone. A holder — later in this run
  or in a later one — resumes it with its own `resume_expr` row and settles on the held
  run's result; a released run's result never re-enters the run that released it. The
  release lasts as long as the held step's park would: the platform's 30-day park-entry
  floor, or longer when the latest deadline the held step reported (its own ask's and every
  caller ask's) plus the redelivery horizon (`INTERACTIONS_IDLE_TTL_SECONDS`, default 1 day)
  ends later. Each later re-park of the released run grows it the same way past the new
  deadline. No deadline refuses an ask exit. A terminal of the released run that arrives
  after the release has lapsed is refused at delivery as a failure, never as the agent's
  result (`no park-index entry for interaction_id '<chain key>'; cannot resume`): the
  resuming holder fails, so its On Error runs, or the flow fails when none is set. A held
  flow is not chained: its ask exit has no release.
* **Send up (`send_up`).** Turn the send-up switch on and the holder parks the ask as a
  nested park and hands it **up** to this flow's own caller unchanged, for a run
  further up to answer. With send-up on, there is no ask exit to wire.

A holder that can ask its caller needs one or the other, or a caller ask has nowhere to
go.

**A run a holder resumed cannot park on it again.** When a holder resumes or takes a held
run and that run asks this run's caller again with send-up off, the new asks route to the
ask exit as usual. When it parks again instead — on a user ask, or on a caller ask with
send-up on — the holder refuses the park with a conflict error: the resumed run keeps the
routing of its first park, so this run could never be continued by its answer. The holder
fails, so its [On Error](#handling-a-nodes-error) runs, or the flow fails when none is set.
Answer such an ask through its own path, or route caller asks through the ask exit with
send-up off.

![A node card with its ask exit wired.](https://mintcdn.com/tai42/C97bEX4Y1-MJSgdV/images/studio/ask-exit-light.png?fit=max\&auto=format\&n=C97bEX4Y1-MJSgdV\&q=85\&s=84a863feb5cc8d7d2dbfca19f050a5d2)

A node card with its ask exit wired.

## Asking your caller

A step inside a flow can ask **its caller** instead of a person: an
[`ask`](/concepts/asking-the-caller) called with `to: "caller"`. It parks the asking
run on the calling run and is answered only when that run **resumes** it — a person
never sees or answers a caller ask. A caller ask always runs asynchronously, and it
carries a `payload` — a structured value handed to the resolving run in place of a
question. The [holder](#calling-another-flow-cancel-resume-start) above is how a parent
flow resumes, takes, or cancels the caller asks its held call raised — see [asking the
caller](/concepts/asking-the-caller) for the model and the door contract behind it.

## Expiry in a flow

An async ask carries a deadline. What a lapsed deadline does is set by wiring, not by
guesswork:

* **A held ask** — an `ask_node` flow called through a holder — derives its behaviour
  from its outcome. Wire the holder's **`expired`** outcome downstream and the ask
  **resumes on expiry**, so that branch runs; leave the `expired` outcome unwired and
  expiry **kills** the held chain instead (the default). The wiring owns it — see
  [wiring an outcome by hand](/babelfish/wire-form#expiry-follows-the-wiring) for the
  exact shape the derivation reads.
* **A raw `ask` runnable** sets its behaviour on the ask itself: its **On expiry**
  control is **end the run** (the default) or **resume with the expired marker**.
  Every `ask` a flow parks on resumes with `{answer, reply_to, params}` as its result; on
  expiry `answer` is the expired marker and the other two are `null`.

## Warm start

A run can be started with some of its nodes' outputs **already supplied**, so those
nodes skip running: a **warm-start** map of node id to fill value. A holder's
`warmstart_expr` rows author that map for a held flow — each row names a node of the
held flow and a jq whose value pre-fills that node's output.

* A row whose jq gives **null** runs that node normally instead of pre-filling it.
* A **filled** node writes the given output and skips its own state writes — it was
  never called, so it records no call and applies no update.
* A node **inside a loop** is filled per round: its value is a list, one entry per
  round, and a null entry or an index past the list's end runs that round normally.

The whole map is checked once at run start — an unknown node, a node whose kind cannot
be filled, an output that fails the node's declared schema, a per-round shape that does
not match the node's loop depth, and an answer a static ask format rejects are all loud
refusals — then consumed per node.

A raw `ask` node's fill is checked against its question format when that format is
**static**: the ask's own `answer_format` (with `options` for a select and `schema` for a
form) is set in its tool arguments, and the node has no expression and no declared inputs
that could rewrite them at run time. The check uses the platform's own question format for
those arguments, so an off-set answer is refused (`warm-start answer for node '<id>' does
not fit its question format: answer must be one of […]`), and arguments the ask itself
refuses are refused too (`warm-start cannot check node '<id>': …`). A node whose format is
built or overridable at run time is filled unchecked.

![The holder panel's warm-start rows.](https://mintcdn.com/tai42/C97bEX4Y1-MJSgdV/images/studio/warm-start-light.png?fit=max\&auto=format\&n=C97bEX4Y1-MJSgdV\&q=85\&s=a7b41b3f3df97a93a6e9539691caf373)

The holder panel's warm-start rows.

## Portable flow files

A flow exports to a single `.babelfish-flow.json` file — the stored graph verbatim —
and imports back the same way. When the flow carries state bindings, the export gains
an optional **`state_bindings` sidecar**: each node's binding travels alongside the
graph with its state names, subject expressions, input injections and updates, and a
stable **schema fingerprint** of the state's declaration at export time. The graph itself is
untouched and the sidecar is never persisted onto the saved preset, so a flow with no
bindings exports byte-identically to the pre-sidecar format and an older file (no
sidecar) imports exactly as before.

On import, the editor offers to re-attach each carried binding against the target
environment's states. A state of that name whose schema fingerprint still matches
re-attaches straight through; when the schema has changed, each bound path is
re-checked and the binding re-attaches only if every path still resolves; a state
that does not exist here, or a bound path that no longer resolves, is reported per
binding and left unattached rather than silently dropped.

## Structured agent output

An agent node can be constrained to return a validated object instead of free text.
Its Settings carry a **Structured output** schema editor — a JSON Schema whose
top-level `title` is required, since the engine uses that title to name the
structured response and refuses a run it cannot produce against the schema. With a
schema set, the node's Output contract renders it live and reads **Output
(structured)**; cleared, the node returns text. The constraint is the
node's own — it shapes what the agent hands back, and downstream steps read the
validated object.

A finished run mirrors that declared shape onto the **actual** result: the value reads
against the schema rather than as a raw tree, and the mirror never hides data that
does not fit it. See [the Flows editor](/babelfish/studio#schema-aware-run-results) for the
rendered view and the guarantees it makes.

## Node waits

A fan-in node runs once its **input barrier** releases, and the barrier has three
mutually exclusive modes set on the node:

* **All inputs (the default).** The node waits for every declared or edge-derived
  input to arrive, then runs.
* **Quorum.** A minimum input count releases the node once any that many inputs
  have arrived; it is purely count-based and never looks at which inputs arrived.
* **Named release.** A named-producer list releases the node once every named
  producer is present in the fan-in — a barrier keyed on specific producers rather
  than a count. Every other input is still consumed if it happened to arrive by
  release time, but is never waited on.

Named release and quorum are **complementary and mutually exclusive**: named
answers "wait for these specific producers", quorum answers "wait for any k of
them", and setting both is rejected at validation. Each named producer must be one
of the node's inputs after edge-merge, and its unwaited incoming edges render as
**dashed, read-only** on the canvas so the optional producers are visible at a
glance.

A named producer counts as present once it produced output **somewhere in the run**
— which is not the same as that output being delivered to your node as a trigger. If
the producer sits behind a conditional whose branch routes elsewhere, its output
lands in state but nothing re-invokes your node, the barrier is never re-evaluated,
and the node simply does not run (the run goes quiescent and completes as success).
When a behind-a-condition producer might route away from you, pair the named release
with a **wait timeout** so a later trigger can force a partial run.

**The give-up pair.** A wait carries an optional **wait timeout** and a
**raise-on-timeout** flag, and the pair is the barrier's safety valve on any fan-in
node — and on an **iterate** (or its **map** face), whose loop entry is itself an
all-or-nothing barrier. Left to force-run (the default), a trigger arriving after the
deadline releases the barrier with whatever inputs are present and the node runs a
partial; set raise-on-timeout and that same lapsed deadline instead **fails the node
loudly**, attributed to the waiting node as an *application* error rather than
infrastructure — so a flow-level On Error sees it exactly as any node
failure and can route on it. The timeout is lazy either way: it
can only fire when some trigger arrives after the deadline, so a node whose last
trigger already fired keeps waiting forever. Because the wait's start clock is
checkpointed, size the timeout against wall-clock park durations — a long upstream
park can make the first trigger after a resume find the deadline already elapsed and
force the give-up immediately.
A run cut short this way says so in its outcome: `missing_results` names every result
surface — a node or a conditional branch flagged to return a result — whose output the
outcome does not carry, on a completed run and on a paused one alike. A paused outcome that
carries no `missing_results` at all means the list could not be computed and is unknown —
never that nothing was missing.

A run whose result cannot be built fails. When a node's return expression raises, the
caller receives the run's error (`Flow run failed (app/<type>): …`) whether the run
completed or was cut short by a stop or an abort. When a run that must return a result has
none, a completed or stopped run fails the same way; an aborted run was cut short on
purpose, so it returns the `aborted` status with the missing results listed in
`missing_results`. The error is an *application* error, since the expression and the check
are the flow's own logic: the flow-level On Error sees it, and it is not retried as an
infrastructure fault.

## Handling a node's error

A node — a **runnable**, an **agent**, a conditional's **branch**, or the flow itself
(its **Start**) — can carry an **On Error**. When a node fails, the On Error runs, its
result becomes the failed node's output, and the run continues from there rather than
aborting. A failing node runs its own On Error, else — when it runs a step of its own, a
**runnable**, an **agent**, a **flow call**, or a **custom node** — the On Error of the route
(or hand-authored branch) that led to it, else the flow's; a **conditional**, an **iterate**,
or a **map** takes no route or branch On Error and resolves failures at the nodes inside it.
In the Studio the same error handle also rides a **Router** card, catching its verdict node's
failure; each **route** on that card, whose On Error covers a **runnable**, **agent**, **flow
call**, or **custom node** the route leads to; and a **Sub-Flow Start**,
where it is the sub-flow's own flow-level On Error.

An On Error's jq reads the failure through `.upstream_outputs`, the same namespace
predecessor outputs use, alongside the ordinary run channels:

| jq path | What it holds |
| - | - |
| `.upstream_outputs.error` | The exception payload as raised — a dict is carried verbatim so jq can navigate it (`.upstream_outputs.error.code == 404`), anything else is its string form. |
| `.upstream_outputs.error_type` | The exception class name, for gating on a specific type. |
| `.upstream_outputs.error_kind` | The platform's stable error label. It survives class renames, so it is the durable key to route on. |
| `.upstream_outputs.additional` | Where the failure happened, and its source. `.failed_node` is the id of the node that failed; for an **iterate** or **map** whose failure reaches the flow's On Error the id is under `.failed_iterate_node` instead, alongside the per-iteration detail described in [When a loop's failure reaches the flow's On Error](#when-a-loops-failure-reaches-the-flows-on-error). When a **route**'s or **branch**'s On Error is the one that runs, `.failed_branch` and `.failed_conditional` also name the branch and the conditional it belongs to; a failing branch step carries those two without `.failed_node`. `.error_source` is `"infrastructure"` when a transport the platform owns failed, and `"app"` for every other failure (see [Who handles a failure](#who-handles-a-failure)). |
| `.inputs` / `.outputs` | The run's inputs and outputs channels at failure — what the [run state](#run-state) keeps. |
| `$states` / `.flow_graph_kwargs` | Declared state and the run's own inputs, exactly as any other authored jq reads them. |

An On Error dispatches one of two ways, and they are exclusive — declaring both
is refused rather than silently preferring one:

* **A wired Recovery.** Name another runnable in the flow as the **Recovery** node; it
  is dispatched only through the On Error, never by ordinary routing.
* **An inline tool.** Attach a **tool** directly to the On Error, with optional
  baseline keyword arguments that the On Error's expression overrides map onto. Any
  registered tool qualifies — including a flow-call preset, which makes the On Error
  an arbitrary **nested flow**.

An On Error may also be a bare expression that shapes a replacement value without
dispatching anything. Baseline kwargs without a tool to receive them are refused, and
an On Error with no tool, node, expression, or (on the flow-level On Error)
[Reply](#the-participant-reply-on-a-failed-run) at all is refused as inert.

> [!WARNING]
>
> A **Recovery-only** node — one no ordinary routing reaches — never runs as a
> live graph step, so an edge **out** of it can never fire and an `inputs` reference
> **to** it reads an output that is never written. Both leave a downstream node waiting
> on its barrier forever, so both are rejected as dead wires. Wire the Recovery node into the
> flow's ordinary routing if you need its output downstream.

Validation also **warns** when a wired Recovery has no incoming routing and the flow
declares no entry points: the builder auto-promotes every unrouted node to a start
entry, so that node would run unconditionally at flow start *as well as* on error.
Wire an incoming edge to it, or declare the flow's entry points explicitly, to keep it
Recovery-only.

**A flow-level On Error is a different job.** An On Error attached to the flow itself —
the Start-attached one — runs only on the terminal error path, and the run still
**fails**. It decorates the failure: it can send a notification, shape the error that
surfaces, or give the person on a conversation route a
[Reply](#the-participant-reply-on-a-failed-run), but it cannot rescue the run.

To recover from a failure and keep running, put the On Error on the failing node
instead. The editor names which of the two you are editing on the form itself, so
the rescuing kind and the decorating kind are never confused.

A finished run shows what the On Error did. A node that failed and was rescued reads
as recovered, and the On Error that ran — whether the inline tool or the wired
Recovery — reads as having run on the error path rather than as an ordinary
step. A node reached both ways keeps its own status and gains the On Error mark.

### The participant reply on a failed run

When a conversation route runs the flow and the run fails, the person reads the route's
failure line. The flow-level On Error's **Reply** gives that person the flow's own text
instead: a jq expression (inline or a stored template) whose result is the reply. It
runs once, at the end of the failed run, and the route sends its result in place of its
`reply_texts.error` or the built-in line
([failure replies](/reference/conversation-bridge#failure-replies)).

* **Flow-level only.** A node's, route's, or branch's On Error cannot carry a Reply; the
  build refuses it there and the editor shows the field only on the flow-level form. Only
  the run's own failure reaches the person, so a nested flow's Reply stays with that run
  and never becomes its parent's reply.
* **It reads the handler's context.** The Reply sees the same `.upstream_outputs` error
  fields, `.flow_graph_kwargs`, and `$states` as the On Error's condition and expression,
  plus the handler's outcome in `.upstream_outputs.additional.handler_result` (or
  `.upstream_outputs.additional.handler_error` when the handler failed). It runs after the
  handler step, whatever the handler's result, so a failed notification never takes the
  reply away.
* **Only a failed run gives one.** A failure the run recovers from gives no reply. When a
  branch hits its iteration limit, the flow-level On Error runs in-graph as that branch's
  fallback: with a tool, node, or expression handler the run goes on and ends as a
  success, so the Reply is never evaluated.
* **The condition gates it.** When the On Error's condition is false for the failure,
  neither the handler nor the Reply applies, and the route sends its own failure line. A
  condition that raises is logged at ERROR and gives no reply.
* **What it returns.** Text of 1 to 2,000 characters that is not blank, or `null` for no
  reply. Any other result — a non-string, blank text, text over 2,000 characters, a jq
  error, or a template that does not render — is a fault: it is logged at ERROR, recorded
  on the On Error's trail entry as `additional.reply_error`, and the failure goes out with
  no reply, so the route's fixed line is kept. A reply fault never replaces the run's own
  failure.
* **A Reply on its own is valid.** A flow-level On Error with only a Reply runs no handler
  and records neither `handler_result` nor `handler_error`; the run still fails, carrying
  the reply.
* **Infrastructure failures skip it.** A failure of source `infrastructure` skips the On
  Error entirely (see [Who handles a failure](#who-handles-a-failure)), so it carries no
  reply.

> [!WARNING]
>
> The person reads the Reply exactly as written. Its context holds internal details — the
> error text and the handler's outcome — so never echo them into the reply. The flow's author
> owns that the reply is safe for the person reading it, just as a route admin owns the
> route's `reply_texts.error`.

### Who handles a failure

Two questions about a failure are answered apart.

**Who handles it — `error_source`.** A failure is `infrastructure` only when a transport the
platform owns failed, as that transport's owner declares it: a standard timeout or connection
error, a dropped or unconnectable pooled client, an HTTP transport error, a closed or broken
stream, or the MCP client's own read timeout. No author caused such a failure and no On Error
can mend it, so it **skips** the node's On Error and reaches the run's error path. Every other
failure is `app` and **reaches** the On Error, whatever its kind — including an MCP tool's own
error, an unanswered sync ask, a spent turn budget, a sandbox command that timed out, a
sandbox, states or other capability that is not available, a tool that paused without
declaring it, a barrier that timed out, and any error raised from a transport error (only the
error itself is read, never its cause). A failure replayed on resume keeps the source it had
when it happened.

| Raised in a node | `error_source` |
| - | - |
| A standard timeout or connection error, a dropped pooled client, an HTTP transport error, a closed or broken stream, an MCP read timeout (code 408) | `infrastructure` — the node's On Error is skipped |
| An MCP error with any other code | `app` — the node's On Error runs |
| An unanswered sync ask, a turn budget, a sandbox exec timeout, a missing sandbox, states or capability, an undeclared pause | `app` — each is stamped `timed_out` or `unavailable` for a reason that is the flow's own, and the node's On Error runs |
| Any error raised from a transport error, a barrier timeout | `app` |

**Whether it is retried — the error kind.** A tool that opts into the platform's retries is
retried on the error kinds the platform treats as retryable. The transport errors above carry a
kind too: an HTTP timeout reads `timed_out`, other HTTP transport errors and a closed or broken
stream read `unavailable`, and an MCP error leased through the platform's client reads the kind
its code means — so `.upstream_outputs.error_kind` names them rather than `unknown`.

### When a loop's failure reaches the flow's On Error

An **iterate** (or its **map** face) resolves its own iterations' errors at the nodes
inside the loop; a failure it cannot contain surfaces to the **flow-level On Error**,
where the run still fails (a flow On Error decorates, it does not rescue). What
`.upstream_outputs.additional` carries then depends on where the loop broke.

* **The loop could not build or run its plan** — its list `input` was not a list, its
  count was not a number, its `while` condition was not a boolean, or a **bounded**
  driver's plan (a resolved list or count) was larger than the max-iterations ceiling.
  `additional` carries `.failed_iterate_node` alone.
* **The body failed while running** — one or more iterations failed inside the body, or a
  `while` loop reached the max-iterations cap without its condition turning false.
  Alongside `.failed_iterate_node`, `additional` carries the two keys below, so recovery
  can name which items failed and read every completed iteration's outcome.

| jq path | What it holds |
| - | - |
| `.upstream_outputs.additional.failure_indices` | The zero-based indices of the iterations that failed, in ascending order. A `while`-cap failure lists the one index that never ran. |
| `.upstream_outputs.additional.slots` | One entry per iteration, in index order — every completed iteration, plus, on a `while`-cap failure, a final entry for the iteration that never ran. Each carries `.iteration` (its zero-based index), `.ok` (true when the iteration produced output and none of it failed), and `.terminals` — the body's end nodes keyed by node id, each a `{ "status": "ok" \| "error" \| "skipped" }` object holding its output under `.value` when it ran, or its failure under `.error`. |

A terminal's `.error` carries a cause only when the failing node is one of the body's
**end** nodes. When a node in the *middle* of the body fails — or a `while` loop hits the
cap — that iteration's end nodes all read `skipped` and hold no cause; read the failure
from the top level instead: `.upstream_outputs.error` summarizes the **first** failed
iteration and the error that stopped it (its type and message) —
`.upstream_outputs.additional.failure_indices` lists every failed iteration — and
`.upstream_outputs.error_kind` is the failures' shared taxonomy label, reading
`"unknown"` when they carry different labels or none. The per-item `.terminals`
are for reading the successful iterations' outputs, not the cause.

## Run condition

Any scheduled node — a runnable, an agent, a flow call, a map, and a router's
verdict node — can carry an optional **run condition**: a jq predicate authored as an
inline expression or a stored template with kwargs (the same field triple every jq
site uses), answering one question — *should this node run at all?* Left empty, the
node is unconditional and runs exactly as it did before the feature existed.

The condition is evaluated at fire time — after the node's input barrier releases and
after its [state refresh](#refresh-opt-in-state-re-read), before the node does any work
of its own, including its own expression — over the same namespace that node's
expression reads. It is **bool-strict**, like a conditional's condition: anything but
`true` or `false` is an authoring defect, and a condition that raises fails the node
down its normal error path. It is statically checked like every other jq slot, so an
unresolvable upstream read or a schema-impossible comparison is a build error.

* **True** runs the node normally.
* **False** *skips* it: the node does not execute, its output is `null`, and its status
  reads **skipped**. The output key is still written, so every downstream input barrier
  still releases and the flow **continues past** the node — the gate stops the one node,
  not the path. To stop a whole path, use a conditional or a router instead.

A skip is not a failure, so a skipped node never reaches its own [On
Error](#handling-a-nodes-error) — the skip happens before any execution that could
fail — and it **settles** the node, so a re-drive of the run re-evaluates nothing. A
node flagged to return a result still contributes its key when skipped, with the value
`null`, so a return expression on a node you might skip must tolerate a null input.

The gate belongs on a **scheduled** node. A node that runs only as a
[Recovery](#handling-a-nodes-error) is dispatched directly and never scheduled, so a
condition on it would never be evaluated; the editor does not offer the field there —
unless one is already stored, in which case it renders with that fact stated, so the
dead value is visible and clearable rather than silently kept.

> [!NOTE]
>
> A node whose tool pauses and resumes re-runs its whole node function on resume, so its
> run condition is evaluated **again** over the resume-time view — one a peer may have
> moved during the pause. A condition that answered true on the first drive and false on
> the resume drive reports the node skipped with a null output even though the tool
> already ran. This is inherent to interrupt-resume re-execution: a condition over values
> that can change while the node waits carries the edge, one over the node's settled
> fan-in does not.

## Run after the reply

A runnable node can call its tool **after the run has answered** instead of during the run:
set `after_reply: true` on the node. Use it for a call the reply does not depend on — saving a
transcript, notifying a team — so the participant never waits on it.

When the node is reached and its run condition holds, the engine does not call the tool. It
queues the call, with its resolved inputs, on the run's states unit of work, and the node settles
at once with a `null` output and the status `deferred` (shown in Run mode as **Node call runs
after the reply**). When the run ends cleanly the call is written with the run's
[pending state save](/concepts/states#pending-saves) and runs after the save's records apply, in
order with every other save on the same subjects — so the call sees the state the run saved. It
runs under the identity, attribution, state context, and trace the run had, with the
idempotency key `<save id>:<index>`. A run that ends any other way (an error, an abort) drops the
call, and a resume never queues it twice.

The node has no output and no place in the rest of the flow, so the engine refuses:

* an `after_reply` node with no `tool`, with `return_result` or `return_expr`, with its own
  `on_error`, or with a `session_thread`;
* an edge out of it, a node naming it in `inputs`, or the node inside an iterate body;
* a state binding with updates on it.

A failed call is not reported to the flow — the run has already answered. A transient failure
is retried; any other failure marks the save failed and holds its subjects, loudly, until an
operator retries or discards it (see [failures](/concepts/states#pending-saves)). Delivery is at
least once: a call interrupted by a process exit runs again only when its tool declares
`tai42/crash_resume`, and otherwise the save fails. A call that parks for an answer fails the
save, since nothing waits for it after the reply. The node needs the
[state store](#enable-the-state-store).

## Routing on a verdict

A **router** node judges its input and routes on the result — one card instead of a
model node wired into a hand-built conditional. You declare the **kinds** it routes on,
each with a name and a description, and the card generates everything the routing reads
from that one list, so the judgment and the routing can never drift apart.

Who does the judging is the card's **[Decided by](#decided-by)** choice — an **LLM
agent** that reads the input and extracts the items of each kind, or a **classifier
model** that answers one yes/no question per kind and returns a probability. The kinds,
the routes, and the routing discipline are the same either way; only the judging half
differs.

Three kinds of edge leave the card, each drawn distinctly:

* **Kind** — fires when the verdict finds that kind. An optional jq guard is
  combined with it, so "this kind, but only when…" stays one edge.
* **Condition** — the branch condition *is* an authored jq expression with full
  access to the run, `$states` included. It is a condition route, not a disguised
  kind, and the canvas says so.
* **Otherwise** — the default branch, taken when no other branch matched.

Several branches may share one target, and a declared kind that is not wired is
still classified — it stays in the generated schema and in the model's output, it
just routes nowhere.

Renaming a kind updates its schema property, its prompt bullet, and the condition that
reads it together, so every wired edge survives the rename untouched; a route's
[key](#route-keys) is your own word and is left as it is. On save the card lowers
to ordinary engine parts — one verdict node plus one hidden conditional — and folds
back into the single card on load, the same way a [map](#looping-over-a-list) folds.
A conditional you author by hand carries no such marker and stays a visible decision.
A saved router whose stored verdict marker still uses the retired `classifier` key
cannot be folded: it is shown as a plain conditional, asking you to re-create the routing.

### Decided by

A router's kinds are judged one of two ways, chosen by the card's **Decided by** control
and offered whenever the host registers either backing tool:

* **LLM agent (the default).** The card lowers to an agent that reads the input, extracts
  the **items** of each kind into a generated structured-output schema, and renders the
  kinds into a system prompt through the `router_kinds` variable. A kind route fires when
  that kind's item array is non-empty; the agent can [loop](#dispatch-once-or-loop) over the
  extracted items, a kind may carry extra per-kind fields merged into each item beside its
  text, and the card may declare [turn-level output fields](#turn-level-output-fields).
* **Classifier model.** The card lowers to a [`classify`](/concepts/classifiers) call that
  asks **one yes/no question per kind** — the kind's name is the question's key and its
  description the instruction — and returns a **probability** per kind. A kind route fires
  when that probability reaches the card's **threshold** (0 to 1, default 0.5), AND-combined
  with the route's optional guard exactly as the non-empty check is under the agent. The
  classifier extracts no items, so it declares at least one kind and offers no loop, no
  per-kind or turn-level fields, and no system prompt; its **provider** and **model** are set
  on the card (an empty provider uses the host's default classifier provider).

Choose the **LLM agent** when the routing needs the extracted items, a loop over them, or
extra fields; choose the **classifier model** for a fast yes/no per kind with a probability
and nothing to extract. Because a classifier declares no output schema, a downstream read of
its per-kind probability is untyped, exactly as [Judging with a
classifier](#judging-with-a-classifier) describes for a Classifier card.

### Route keys

Every route row — a **kind** route, a **when** route, or the **otherwise** row — carries a
**key**, the name of that route's branch. A key is an identifier — letters, digits, and
underscore, never starting with a digit — and is unique across the router's rows.
`otherwise` is the reserved key of the otherwise row.

A kind route's key is prefilled with the kind's name when the row is added, so the common
one-route-per-kind card reads by kind with nothing to fill in. Add a second route for the
same kind and it starts unnamed — the prefill fills a name only when no row of the router
already holds it — and the row is flagged until you name it; a **when** route always starts
unnamed. Renaming a kind never rewrites keys: a key is the word you chose, and the card
offers no auto-rename.

The key names the route's branch in the saved flow and in every trace, as
`<conditional>__<key>` for every row, so the branch a trace points at is the word you chose
rather than a position — there is no index in it. Reordering rows never changes that branch:
under first match the row order rides its own separate [carrier](#every-match-or-first-match),
not the branch name. Renaming a route's target leaves it untouched too, since a target is
only the edge drawn on the canvas. Renaming the **key** itself does rename the branch, so
choose it before the traces you rely on are recorded.

A row left unnamed, or given an invalid or duplicate key, is refused loudly — it blocks
save, export, duplicate, and run, with a message naming the router and the route — until you
fix it. On the card, a **condition** chip shows its key above its target, and a **kind** chip
shows the kind name with its route keys on a second line beneath — shown when a key differs
from the kind name or the kind carries several routes, and omitted for a single route keyed
by the kind name. Under **Loop** dispatch a kind line is a loop body, so its key is the
kind's name and is read-only.

### Every match or first match

A router's routes fire under one of two **routing** disciplines, set on the card:

* **Every match (the default).** Every route whose condition holds fires, in parallel
  — the multi-fire fan-out. This is the default discipline and carries no wire marker:
  Every match emits no routing-discipline key on the wire.
* **First match.** The routes are evaluated in **row order** and only the **first** one
  that matches fires; the rest are never evaluated. This is the classic single-path
  routing table — at most one route ever fires.

Because a router lowers to a hidden conditional, its routing *is* that conditional's own
routing discipline and its routes *are* the conditional's branches: a kind route or a
when route is a predicate branch, and the single **otherwise** route is the default
branch, taken only when nothing else matched.

Under first match, row order is **semantic**, so it cannot ride the member order of a
JSON object — object member order is not meaningful and does not survive every store a
flow passes through (Postgres `jsonb`, for one, re-keys members by key length then
bytewise). The order instead rides an explicit **array** of route keys that no store can
permute, written on save from the routes table below. A first-match router with routes
must carry it — one without it is refused at load. The array must list every route
exactly once — a partial or unknown listing is refused at load rather than guessed at
runtime.

First-match order carries two guard rails, refused loudly at load and scoped to first
match (every-match routing is order-free, so neither rule constrains it):

* **At most one catch-all, and an unconditional one comes last.** An always-true route
  makes every route below it unreachable, and a second catch-all can never fire — so
  declaring either is refused with the dead rows named. A plain **otherwise** route is
  order-free (it fires only when nothing matched, wherever it sits) and may be declared
  anywhere.
* **Route keys are never plain numbers.** A numeric branch key is an array index that a
  JSON-object client silently re-orders ahead of every other key; the router never mints
  one, and the engine refuses it whether or not an order carrier rides, so the two
  spellings of a first-match table cannot disagree.

### The routes table

Below the card, the **routes table** is one view over the router's routes: one row per
wired route, in the order they lower. Each row shows its flavor — **kind**, **when**
(the table's name for a Condition route), or **otherwise** — its **key**, the kind or
when-condition, an optional per-kind **guard**, its **target**, and a per-route **On Error**
switch. Conditions, guards, and keys are edited in place; a route's target is the edge you
drew from its chip on the card, so the table **shows** it, never picks it — the canvas
stays the one place edges are drawn.

A kind row's guard is AND-composed with the pinned non-empty check for that kind, so the
route fires only when the kind matched *and* the guard holds. A when row's condition *is*
its branch condition, reading the classified output, other node outputs, and `$states`.

Under **first match** the table also **orders** the rows — the row number is the
evaluation priority. Reorder a row two ways: drag it by its grip, or step it with its
move buttons (the keyboard and assistive-technology path). The reorder is a plain array
move with no wire format of its own; targets, guards, and conditions ride along
untouched. Under the every-match default the order is only a position, so the reorder
controls are absent.

The table also carries **advisory** notes — never a block on saving — when a first-match
row is already covered by an earlier one, when a row repeats an earlier one to the same
target, or when the otherwise row sits above rows still being evaluated and so reads out
of order.

### Turn-level output fields

A router can describe not just the items it **extracts** but facts about the **whole
turn**. Beside the kinds, declare optional **turn-level output fields** — a JSON-Schema
`properties` fragment merged into the generated response format and required alongside
the kinds — so a field like `flagged` or `sentiment` becomes an ordinary top-level output
read as `.upstream_outputs.<router>.flagged`, typed and statically checked like any other
output rather than modelled as a kind or dug out of an item. The declaration rides the
card's marker exactly as the kinds do (the response format is regenerated on every save)
and follows the same absent-key discipline as the routing mode: declare none and the router is
byte-identical on the wire. Because a turn field and a kind are siblings in one output
namespace, a turn field named after a kind — which would shadow that kind's array — is
refused.

### Dispatch: once or loop

A router runs its chips under one of two **dispatch** modes, set **once on the card** —
never per route. The chips look and connect the same way in both modes; the mode alone
decides what a chip's line means, while the routing discipline above still orders the
routes:

* **Once (the default).** Every chip is a plain routing line: the flow continues from
  each matched chip, and the target reads the whole verdict as
  `.upstream_outputs.<router>`. This is the router exactly as above — no result chip, and
  a card on Once emits no dispatch key on the wire.
* **Loop.** Every chip's line starts a **body** — any nodes and conditions you draw off
  the chip, in the same flow — and that body runs **once per classified item** of the
  chip's kind. The runs go **sequentially** or **in parallel** (a parallel run takes an
  optional **max concurrency** cap), or the body repeats **while** an authored jq
  condition holds. A looping card grows one **result chip**, the loop-done exit the
  collected output leaves through.

A looping body sees its one item as `$iterate.item`, the run index as
`$iterate.iteration`, the prior runs as `$iterate.prior_outputs`, and the whole verdict as
`.outputs.<router>`. A **while** body runs its first round unconditionally, then evaluates
the condition before every further round — `$iterate.prior_outputs[-1]` is the previous
round's result and `.upstream_outputs.<router>` the verdict — bounded by a **max runs** cap
(the flow's own cap by default) that is a safety backstop, not a stop condition: exceeding
it stops the flow with an error on the ordinary [`on_error`](#handling-a-nodes-error) path.
A while body is always sequential — the engine refuses a parallel run under a while
condition.

There is never a branch node between a chip and its body — the line goes straight to the
body's first node. Because a body has a single entry, a chip under Loop carries exactly one
line, and the card refuses to switch from Once to Loop while any chip still fans out to
several lines — remove the extra lines first. One looping chip beside plain ones needs no
Loop card: keep the card on **Once** and draw an ordinary [Iterate](#looping-over-a-list)
after that chip. Fanning one chip out to several targets at once is several Once lines from
that chip under every-match routing.

**The result chip.** Under Loop the card grows one **result chip**, and the collected
output of every chip leaves through it, keyed by **kind name**. A consumer of the result
line reads a kind's aggregate as `.upstream_outputs["<router>__result"].<kind>` (the
bracket form, because the collector's name carries `__`). The aggregate is a list in run
order — item order for a per-item body, round order for a while body; a kind the verdict
did not produce reads `null`, and a matched kind with no item reads `[]`. Because the key is
the kind name the author sees on the card, renaming a kind changes that visible key, and the
editor's upstream hints route the result line through the collector's shape.

**Loop and the routing discipline.** A looping chip is not a row of the hidden conditional,
so the [first-match](#every-match-or-first-match) discipline orders the card's **when** and
**otherwise** routes only: a chip's body runs whenever its kind matched, regardless of first
match. The single **otherwise** route still fires only when nothing else on the card did —
under Loop it carries an explicit condition over every kind and when route, so it never
double-fires beside a matched kind.

![A Router card on Once with the kind chips alpha, beta and gamma, each wired by a plain line to its own runnable, beside the + when and otherwise chips; no loop badge and no result chip.](https://mintcdn.com/tai42/C97bEX4Y1-MJSgdV/images/studio/router-once-canvas-light.png?fit=max\&auto=format\&n=C97bEX4Y1-MJSgdV\&q=85\&s=8c37b80f773b0929b0989972ee8b7cb1)

A Router on Once: every kind chip is a plain routing line.

![The same Router card on Loop: the loop badge, the kind chips alpha, beta and gamma each wired to the body it runs, and the wired result chip the collected output leaves through.](https://mintcdn.com/tai42/C97bEX4Y1-MJSgdV/images/studio/router-loop-canvas-light.png?fit=max\&auto=format\&n=C97bEX4Y1-MJSgdV\&q=85\&s=e45223984fc45d745e451ef952e15f97)

The same Router on Loop: each chip starts a body, and the result chip continues when every body is done.

![The Router's Dispatch field with Loop chosen: the Once and Loop control, the Order choice, the Repeat while a condition holds checkbox with its jq condition, and the Max runs cap.](https://mintcdn.com/tai42/C97bEX4Y1-MJSgdV/images/studio/router-dispatch-form-light.png?fit=max\&auto=format\&n=C97bEX4Y1-MJSgdV\&q=85\&s=52c293d5c7e66ee8672c0f3d8aa7fa31)

The Router's Dispatch field with Loop chosen and a repeat condition revealed.

### Per-route On Error

Every route — kind, when, or otherwise — can carry its own **On Error** that catches the
failure of **the node the route leads to** when that node runs a step of its own — a
**runnable**, an **agent**, a **flow call**, or a **custom node**: its result becomes that
node's output and the run continues downstream from there, exactly as a node's own On Error
does. A route leading to a **conditional**, an **iterate**, or a **map** is not covered here —
those resolve failures at the nodes inside them. It still covers a
failure of the route's own **branch step** — the branch's preparation, such as a branch
hitting its iteration limit. The target node's own On Error, when it has one, runs instead,
and nothing further downstream is covered — every node past the target is resolved by its own
lookup.

Each route's **On Error** switch sits in the routes table, off by default. Switched on, the
route's On Error takes one of two exclusive forms — the same two
[an On Error card](#handling-a-nodes-error) offers:

* an **inline** tool on the row, with its own expression and condition; or
* a **wire** from the route chip's **error dot** to an **On Error** node on the canvas —
  that node then holds the handling, its own inline tool or its wired **Recovery**, as any
  On Error node does.

The router card's own On Error is separate: it still catches the **verdict node's** failure, so
a route's On Error and the card's On Error cover different failures. Under **Loop** dispatch a
kind chip is a loop body, not a branch, so a kind route carries no per-route On Error there;
**when** and **otherwise** routes carry theirs in both dispatch modes. A switch left on with
neither form filled is a blocking error that names the route, refusing Update until you fill a
form or switch it off; and switching a wired route off leaves its On Error node on the canvas
unattached, to delete or re-wire before you save.

For example, a router `sorter` with a route keyed `high_total` can switch that route's On
Error on and pick an inline `notify` tool — or, instead, wire the route's error dot to an On
Error node whose Recovery is a runnable `status_update`. Either way, when the node the route
leads to fails, the On Error's result becomes that node's output and the run continues
downstream.

## Judging with a classifier

A **Classifier** card judges its input and hands the judgment downstream — one card
instead of an agent wired into a hand-built conditional. It lowers to a single
[runnable](#inputs-and-results) that calls the [`classify`](/concepts/classifiers)
tool: you declare a set of **typed questions** — each a **Yes/No**, a **Pick one**, or
a **Rate** — and the card returns one answer per question, keyed by the question's
name, carrying a probability. The card is authored on the
[Classifier card](/babelfish/studio#the-classifier-card) in the Studio; the three
question kinds and the answer shapes are covered on the
[classifiers](/concepts/classifiers) page.

The card's **input expression** is the runnable's input jq: it must return an object
with a `state` key — what the classifier reads. Left empty, the whole upstream input
is judged.

A downstream condition reads an answer at `.upstream_outputs.<node>.answers.<key>`,
where `<node>` is the card's name and `<key>` is the question's name. A Yes/No answer
carries its probability under `.noul`, so a threshold guard reads, for a card `judge`
with a question keyed `urgent`:

```
((.upstream_outputs.judge.answers.urgent.noul) // 0) >= 0.5
```

A `choice` answer carries `.choice` and per-label `.probabilities`, and a `score`
answer carries `.score` and a per-level distribution. Every answer stays inside what
the card declares: each question gets one answer of its kind, a `.choice` is one of the
question's labels, and a `.score` lies within its levels. The platform refuses a
response outside them, so the card's node fails, its [On Error](#handling-a-nodes-error)
runs, or the flow fails when none is set (see [Answers stay inside what the request declares](/concepts/classifiers#answers-stay-inside-what-the-request-declares)).
A condition never needs to check that an answer is present or that `.choice` is one of
the labels. Unlike an agent's
[structured output](#structured-agent-output), a classifier node declares no output
schema the comparison guard can read, so downstream reads of its answers are untyped
operands: they are never statically type-checked and a numeric guard like the one
above always passes the studio's static type check — the shape is the classifier's contract, not a
declared schema.

## The visual jq editor

Every jq expression a flow carries — a node's expression, a branch or loop
condition, a binding's injection or update jq — is authored in one field two ways: by typing
jq into the field's resting text control, or in a **visual editor**, opened from that
control, that draws the expression as a small, editable node graph and writes it back
as jq. The wire always carries the jq text.

> [!NOTE]
>
> This visual editor is [**jq-studio**](/studio/jq-editor) — the platform's
> open-source, built-in jq editor. The [Studio SDK](/reference/studio-sdk/index)
> re-exports its `JqField` component and the Studio host provides the design system and
> evaluation worker, so the flow editor renders it directly, with nothing to install.
> The **same** editor serves every jq field across the Studio — a flow's, a host
> feature's, another plugin's — so the canvas below is identical everywhere. See
> [Visual jq in flows](/babelfish/jq-editor) for the flow field's tabs and per-surface
> seeding.

**The node vocabulary.** The canvas paints eight node kinds, each with a semantic
hue shared with the flow canvas so a colour means the same thing in both editors:

* **Input** (primary) — the data the expression receives, `.`.
* **Value** (muted) — a literal or a path into the input.
* **Operator** (muted) — combines two values (`+`, `==`, `//`, …).
* **Condition** (warning) — chooses a result with if / else.
* **Try/Catch** (danger) — runs logic and recovers on error.
* **Call Function** (primary) — applies a built-in or defined function.
* **Define Function** (primary) — declares a reusable function.
* **Comment** (muted) — a note; never runs.

Kinds that share a hue (Input, Call Function, and Define Function on primary;
Value, Operator, and Comment on muted) wear a terse kind badge and are further
told apart by glyph and shape, so two same-coloured cards never read alike. A
**Legend** on the toolbar lists every kind and the wire notations — pipe, operand,
and function grant — generated from the same registry the canvas paints from, so it
can never drift from what you see.

**The editor shell.** Around the canvas sits a **Test** panel that runs the
generated jq against sample JSON — seeded per surface with a skeleton of the right
input shape, editable, and run locally in WASM (Cmd/Ctrl+Enter) — plus, where the
engine exposes a matching validator, a **Validate** action that checks the
expression server-side. A **live readout** shows the jq the graph currently
serialises to as you edit, and an **error summary** chip counts the graph's problems
and jumps the view to each one in turn.

**The faithfulness guarantee.** The editor draws a graph only when it can prove that
reading the graph back gives exactly your expression. Before any loaded expression
is adopted for editing, its graph is serialised back to jq and a WASM oracle checks
that the two behave identically; only a faithful round-trip is drawn. Everything else
is non-destructive: an expression the editor cannot draw, or one whose graph would
read back differently, keeps your text verbatim and shows it as text with a neutral
**"not shown here"** notice — your expression is never altered, and the editable
canvas is reached only through an explicit **Start empty** that you choose. This
keeps two questions apart — *is the jq valid* and *can the editor draw it*. Only jq
that genuinely fails to compile raises a loud **"invalid expression"** alert; valid
jq the editor cannot represent is neutral, never flagged as broken.

**Where you open it.** In a flow field, the visual editor opens from the **Inline**
tab's **Visual editor** button — the field is a two-tab Inline/Template control, and
the canvas is never a tab of its own. See [Visual jq in flows](/babelfish/jq-editor)
for the field's tabs. The same editor opens the same way on every other jq field in
the Studio.

### Visual jq on every surface

Every jq field carries the same editor, and each names what `.` is at its site so the
Test panel seeds the right sample and the server validator checks the right shape. The
per-site input shapes — the node, error, binding, and return envelopes, the loop
envelopes a `while`/`foreach`/`map` field sees, and the bare flow-inputs and
state-record documents — are listed in
[Visual jq in flows](/babelfish/jq-editor#what-each-field-seeds).

## Flow states

A flow's durable cross-run memory lives in the platform
[state store](/concepts/states): named, schema'd JSON documents, one per subject,
that every door reads and writes through one seam. The engine does not own that
store — it **binds** to it. Declaring a state, attaching a template, browsing records,
and folding subjects are platform concerns (see the [States concept](/concepts/states));
what the flow engine owns is the binding: which states a node reads and writes, under
which subject.

* **Bind a node to a state.** Each node carries a binding document — one or more
  states, each with the templates it uses, a jq `subject_expr` that picks the subject,
  an optional `scope_expr`, **input injections** evaluated after the node's input is
  assembled and before it runs, and **updates** applied after the node completes. Its shape and the
  injection and update forms are in
  [Binding a node to a state](#binding-a-node-to-a-state). In a run, every bound state's
  record is available to jq as `$states.<name>`, seeded once at run start.
* **Subjects.** A `subject_expr` is **required** on every binding and resolves to a
  [subject reference](/concepts/states#subject-references) — a full subject object
  `{target_kind, target_name, kind, key}`, a `{kind, key}` object, or a bare **key** string —
  which the platform resolves at run start by the same rule as every door; see
  [A binding's subject and scope](/concepts/states#a-bindings-subject-and-scope). A
  `subject_expr` resolving to `null` is a loud mint-door error naming the state and the
  expression; a reference the platform refuses fails the run with the platform's refusal.
* **Write through updates.** An update's op batch may carry
  [keyed list ops](#keyed-state-list-ops) and per-op compare-and-set
  [guards](#cross-flow-state-writers) — the coordination primitives for many writers on
  one record; the platform applies every op atomically under the record's row lock.
* **Refresh.** A node can opt into a fresher view of its bound records — see
  [refresh](#refresh-opt-in-state-re-read).

Flow bindings register a `flows-states` section in
[backup and restore](/operate/backup-and-restore); the record data is platform state,
backed up with the store like checkpoints. A node's binding writes land in the platform
record's [audit trail](/concepts/states#the-audit-trail) with the writing consumer, node,
and run, and emit a state-change event into the run's
[Langfuse trace](/plugins/tai42/monitoring-langfuse).

### Reading a state a flow does not bind

The run's `$states` view carries only the states **bound** to the running flow, so a
`$states.<name>` read of a state the flow does not bind resolves to null at runtime.
The engine catches this in two stages — a warning while you author, a loud error when
it runs:

* **A warning while you author.** Flow validation reports a `$states.<name>` read of a
  state that is **not declared** (`state_ref`), or is declared but **not bound** to
  this flow (`state_unbound`), or a `refresh_states` naming an unbound state
  (`state_refresh_unbound`), as a **warning** — never a save gate. The fact is
  extra-graph and per-environment: the read is fixed by binding the state at a separate
  door, so a flow authored or imported before its states are bound in this environment
  is not blocked. The message names the read and the fix, for example: *"Node 'n':
  return\_expr reads \$states.x, but 'x' is a declared state that is NOT bound to this
  flow, so the read resolves to null at runtime. Bind 'x' to this flow, or read a state
  it binds. States bound to this flow are \[…]."*
* **A loud error when it runs.** A `refresh_states` naming a state the node does not
  bind is a loud drift error at node execution: *"node 'n' refresh\_states names state(s)
  \['x'] that are not bound on this node; bound states are \[…]."* A binding whose
  `subject_expr` cannot resolve is likewise a loud mint-door error naming the state and the
  resolved value.

A call to a [template jq](#state-templates) is judged per environment too. Every flow jq
is compiled when the flow is saved, so a program that is not valid jq — a syntax error,
an undeclared `$variable`, a `tjq_<name>` call without its one argument — is refused at
every save door. Whether the template a `tjq_<name>` call names is attached depends on
the environment: a preset write, which carries no environment, admits the call; flow
validation by the flow's name (the editor's save) and a conversation-route bind refuse it
as an **error** when the flow's bound states do not attach the template — *"B: expr:
failed to compile: jq: error: tjq\_total/1 is not defined …"* — fixed by attaching the
template or binding a state that attaches it; and a run in an environment that never
attaches it fails the node with the same compile text.

Binding is refused at the bind door for a state that is **not declared** (*"state 'x'
is not declared"*), for a missing or blank `subject_expr` (it is required and must be a
non-empty jq expression), and for a `subject_expr` or `scope_expr` that is not valid jq.

### Cross-flow state writers

Because overlapping writers are allowed rather than refused, where two flows race
on the same field an optional **compare-and-set guard** opts one op into lost-update
protection. A guard rides any op in an update's batch as a `{path, expected}` pair:
`expected` is the concrete value a custom update's jq computes into the op, and at
write time — **under the record's row lock** — the platform compares the record's
current value at the guard path (a missing path reads as null) to it by strict
JSON equality. Equal, and the op applies; unequal, and that one op is
guard-skipped while the rest of the batch still applies, observable both in the
record and in the run's state-change trace.

The idiomatic use is a **writer token**: pair a field with a companion writer field,
and have each flow guard its write of the field on the writer equalling its own
token, so under a real write race exactly the token-holder writes. The guard is
deliberately narrow — it protects against lost updates only, not multi-step
invariants, and it compares equality on exactly one path (a null expected value
means "expect the field absent or null", the first-claim case). It is a state-store
primitive, checked on every op the store applies.

### Keyed state list ops

A state field that holds a **list of objects** — vetoes, line items, participants —
can be maintained item by item without ever reading the whole list and setting it
back. Five path operations do this **atomically at write time on the live record**,
under its row lock:

* **`set_by_key`** — update or append the list item whose key field equals a given
  value. The op's `value` is the **item** itself: a JSON object that must carry
  its own key field, so the match key can never drift from the payload. The first
  item whose key field equals that key is replaced in list order; if none matches,
  the item is appended (upsert). An absent list is created. The `value` may also be
  a **list** of complete items, applied in payload order — one op, many upserts.
* **`merge_by_key`** — patch fields on items that already exist. The op's `value` is
  a list of **partial** items, each carrying the key field; each partial is
  shallow-merged into the first stored item with that key (`{**existing, **partial}`,
  top level only — a nested object replaces wholesale rather than deep-merging).
  Null-valued fields are dropped before merging, so `null` never deletes a field. A
  partial matching nothing is skipped: unlike `set_by_key` this **never inserts**.
* **`unset_by_key`** — the deleting dual of `merge_by_key`: remove named fields from
  items that already exist. The op's `value` is a list of entries, each exactly
  `{<key_field>: <key>, "fields": [<name>, …]}` — the item's identity plus the
  top-level field names to delete. An already-absent field is an idempotent no-op and
  an entry matching nothing is skipped; the key field itself may never be listed,
  since an item keeps its identity. Stray keys on an entry, a duplicate field name,
  and a duplicate entry key are all refused loudly.
* **`set_by_key_each`** — the keyed **fan-out** of the upsert, for a classifier
  envelope. The op's `value` is an object mapping fan-out keys to lists of complete
  items; each `(key, items)` pair applies the `set_by_key` list semantics into the
  list one level deeper, at the path plus that key. One op and one atomic apply
  replace one op per fan-out key. A fan-out key must be a non-empty string and
  never `"-"`; a key mapping to an empty list contributes nothing.
* **`remove_by_key`** — remove the list item(s) whose key field equals a given value.
  The op's `value` is the **key** to remove by — a single scalar, or a **list of
  scalars** (the MongoDB `$pull` + `$in` idiom) that drops every item matching *any*
  listed key across all of them, in one op. Every matching item is dropped; zero
  matches, or an absent list, is a quiet no-op. A remove list is capped at **200
  keys**; a nested container or a duplicate key is refused loudly, while an **empty**
  list is accepted as a no-op — a jq selection that legitimately matched nothing lands
  as a traced no-op rather than raising.

Every keyed op names a `key_field` — a single **top-level** field of the item
objects — and addresses the **list** itself (for `set_by_key_each`, the object holding
the fanned lists), never a new item, so the append token `"-"` is refused: the op
decides insert-versus-replace by key, not by position. A key is a **string or
integer** only; floats, booleans, null, and containers are refused as fragile
identities, and a payload list refuses duplicate keys loudly. A list item that is not
an object, or one missing the key field, never matches (and is never an error); a
non-list already sitting at the path is a loud refusal. As with any op, a null
`value` contributes no write.

`set_by_key`, `merge_by_key`, and `unset_by_key` touch exactly **one** stored item
per supplied key — the first match. `remove_by_key` keeps its remove-**all**
semantics.

This is the race-free "update the item where key equals X" that a whole-list `set`
could not express — a whole-list write reads, edits, and sets the entire list back,
so a concurrent writer's change is lost. Applying by key under the row lock instead
makes three multi-writer patterns safe with no extra coordination:

* **Distinct keys compose.** Two flows that upsert items under different keys both
  land — exactly like list appends, which always compose.
* **Appends compose with a keyed update.** One flow appending a fresh item while
  another updates an existing one by key keeps both, whatever the commit order.
* **The same key from two flows needs a guard.** Two flows racing to write the *same*
  key each replace the whole item, last-writer-wins; where that is a genuine race,
  pair the op with a [compare-and-set guard](#cross-flow-state-writers) (the
  writer-token pattern).

A **key change** is expressed as `remove_by_key(old)` followed by `set_by_key(new)`
in the **same update** — one batch, one transaction. An update authors its op batch as
a template `update` program (with its adapter form) or a custom jq that returns the
batch, so the keyed ops ride what that jq yields rather than a per-op picker; a run's
state-change trace renders a keyed write by its op and path — `set /items where id = a`
or `removed /items where id = a`.

### Refresh: opt-in state re-read

Every run seeds its bound records into `$states.<name>` **once, at mint** — so a node
reads whatever was persisted when the run started. A node can opt into a fresher view:
set **refresh state** on it to re-read the persisted record(s) right after its input
barrier releases and **before** its jq input is built, folding the freshly committed
docs into `$states.<name>` for that node's own expressions *and* its binding's input
injections and updates. Refresh re-reads **every** state this node binds, or you narrow
it to a named subset.

The node's own control has three states:

| Node setting | Effect |
| - | - |
| *unset* | Inherit the flow's default. |
| *off* | Never refresh — an explicit per-node off-switch that **beats** a flow default. |
| *on* (or a named subset) | Re-read every bound state, or just the named ones. |

A flow sets `refresh_states_default` once and every node that leaves its own control
unset inherits it, so a flow whose nodes should all read fresh does not repeat the
setting on each card. A node that sets its own value always wins — including the
explicit off, which is why the control is three-state: "off" and "not configured"
are different answers once a flow default exists. With no flow default and no node
setting, a node reads the mint-time snapshot.

The default is scoped to the flow that declares it. A subflow dispatched as a tool
compiles from its own graph and resolves against its own config, so a parent's
default never crosses the flow-call boundary in either direction. A `SubFlowStart`
card therefore edits the **sub-flow's** default, and offers that sub-flow's bound
states as its subset options — never the parent's.

* **What it heals — and what it does not.** Refresh heals **causality**: a document an
  already-**finished** upstream node (or another completed flow) committed after this
  run's mint-time seed, or a write whose channel update was rolled back at an interrupt
  boundary. A [subflow](#inputs-and-results) a parent node invokes is this case — its
  updates commit immediately but stay invisible to a later parent node until that node
  refreshes. It is **not** a race primitive — the re-read is a single point-in-time
  snapshot with no lock span, so a writer racing *concurrently* is still a
  [keyed-op](#keyed-state-list-ops) or [compare-and-set guard](#cross-flow-state-writers)
  concern, never this one. A record that reads **absent/erased** skips the landing
  entirely: a refresh cannot observe a deletion.
* **Once at loop entry.** On an **iterate** (and its **map** face) the re-read fires
  **once, at loop entry** — re-entries through the body back-edge skip the barrier — so
  every iteration's body, and any `while` predicate, inherits the same entry-time
  refreshed view.
* **Interrupt-resume caveat.** A tool node that pauses and resumes re-runs on resume, so
  its refresh re-reads at **resume** time and its injections and updates — and the input
  recorded for the node — are recomputed over the resume-time view, which can diverge from
  the arguments the tool actually received on the first drive.
* **Stateless bypass.** On an unbound run — a raw-graph surface, or a flow imported to an
  environment where it is unbound — the re-read is a silent no-op, the same shape as the
  binding's writes. But naming, in the subset, a state this node does **not** bind is a loud
  binding error naming the node's bound states, whenever bindings do load.

In the Studio the control sits on the node's State/Settings surface beside the wait
knobs, and a refresh lands in the run's [state-change trace](#flow-states) as a
"refreshed" marker carrying no new writes. The marker holds the document the node read when
the run's trace does not record it yet (a write from outside this run), and no document when it
does — a node of this run, a subflow of this run or an earlier drive of this run wrote it; the
node's records reference that record.

### Enable the state store

Flow bindings read and write the platform [state store](/concepts/states), so that
store must be enabled — it defaults to the `default` database and points elsewhere
with `TAI_DB_BINDING_STATES` (see
[enabling the store](/concepts/states#enabling-the-store)). The flow engine keeps its
own small store for the per-node bindings, on its own Postgres
component `flows-states`:

```bash theme={null}
TAI_DB_BINDING_FLOWS_STATES=default
# plus the TAI_DATABASE_<NAME>_PG_* settings for that database
```

Then run the migrations — the plugin ships its chain under
`migrations_component: flows-states`, discovered by the shared runner:

```bash theme={null}
tai db migrate
```

The boot gate refuses to serve a declared-but-unmigrated database, naming that exact
step. With the binding unset the feature is cleanly off: bound flows simply run
stateless, and the binding routes answer a gated refusal.

| Variable | Default | Effect |
| - | - | - |
| `TAI_DB_BINDING_STATES` | `default` | Database the platform [state store](/concepts/states) binds to (records, declarations, templates). |
| `TAI_DB_BINDING_FLOWS_STATES` | unset | Database the flow-engine binding store binds to; unset = flow states off. |

Record retention is a platform concern now — set it per state (`retention_days`) or as
a deployment default on the store; see the [States concept](/concepts/states#enabling-the-store).

## State templates

A **state template** gives a state a *declared structure* — a reusable schema fragment,
per-path writer regimes, a declarations section, a set of **template jq** programs, and a
trace switch — written in **template-relative** names that attaching translates to concrete
paths once. The template is a platform document (`kind: "state-template"`) the platform
[state store](/concepts/states#templates-and-attachments) owns; declaring it, attaching it on
a state, its [template jq](/concepts/states#template-jq), and the effective schema an
attachment composes into are all platform operations. A template is data and the runtime is
generic: nothing in a template is a use-case feature — it is a mechanism any state can reuse.

Babelfish consumes an attached template two ways: a node's
[binding](#binding-a-node-to-a-state) injects an `input`-purpose template jq's value into the
node input and applies an `update`-purpose program's op batch after the node runs; and every
jq expression on a bound state may call the input programs through the
[template-jq prelude](#the-template-jq-prelude).

### Binding a node to a state

A node's binding attaches one or more states, each with the templates it uses, a
`subject_expr` that resolves the record key, and an optional `scope_expr`. It carries two
lists:

* **input injections** — each evaluates a `purpose: "input"` template jq (or a custom jq
  reading the bound record as `.` with the run input as `$input`) and merges the value into
  the node input under a named field before the node runs;
* **updates** — each applies a write after the node completes: a `purpose: "update"` template
  jq (its returned op batch rebased under the attachment path), shaped by an **adapter** that
  reads the node's output as `.` with the run input as `$input` to build the program's declared
  input, or a custom jq reading the node's output as `.` with the bound record as `$record` and
  the run input as `$input`, returning the op batch itself. An optional `op_id` — a jq reading
  the node's output as `.` with `$input` — makes the write idempotent.

A binding always attaches **at least one state**: `PUT /api/babelfish/bindings/{flow}/{node}`
with zero states (`{"states": []}`) is refused (`422`). "No binding" is spelled by the
**absence of the document**, never an empty one — `DELETE` on the same route removes a node's
binding, and export carries no empty binding document (a node with no binding contributes
nothing to the [`state_bindings` sidecar](#portable-flow-files)).

The engine validates the binding at save: every named template jq resolves through the
platform's [template jq resolution](/concepts/states#template-jq) — so a name the platform
would refuse at run time (unknown, declared by two templates attached on the state, or used
with the wrong purpose: `input` for an injection, `update` for an update) is refused at save
with the platform's message — and must name a program of a template the binding attaches; an
adapter — required
on a named update — and a custom update's jq must **compile**. It does NOT re-check the ops a
custom update produces: those are constrained at RUN time by the platform's write-regime
chokepoint (there are no binding-declared paths for a custom update). An adapter's output is
validated against the update jq's declared input at APPLY time — a missing or undeclared key is
refused.

The **single-writer** check runs at save over the REAL write paths. A `single`-regime path
of any template attached on the state (one the save itself attaches on use included) admits at
most one writer, and a second is refused naming both. A template update is one writer
identified by `(template, attachment, program)` on its declared `writes` rebased under the
attachment path — so the same template update applied from any node or door on one state is ONE
writer — while a custom update is the node's own writer, `(flow, node)`, counted as a writer of
the **whole attached subtree** (its attachment's path). A `composing` path admits only
[keyed ops](#keyed-state-list-ops) or an append `set` (a path ending `'-'`); a whole-path write
is refused, and the platform store additionally refuses a `composing`-shape violation at write
time, so the rule holds even for a write that never passed the bind door.

The save resolves every named template jq it checks — its own and those of the stored bindings
on the same states — in one call to the platform's batch resolver, under the same per-state lock
the single-writer check reads the stored bindings with. A stored binding whose reference no longer
resolves (its template was detached) contributes no writer and never fails the save.

### The template-jq prelude

Every jq expression a flow carries on a bound state — a node expression, a router verdict, a
binding field — reaches the state's attached templates' `input` programs through a generated
prelude. For each `purpose: "input"` template jq the engine emits one def:

```
def tjq_<name>($params): <the program body, with $params, $declarations and $parameters bound>;
```

so an expression calls it as `tjq_<name>({…})` — always exactly one object argument (`{}` when
the program declares no params), for example `tjq_due_set({run: .turn.run})` or `tjq_x({})`.
Inside the body `.` is the attached record subtree, and `$declarations`/`$parameters` are the
attachment's declarations and parameters. The engine reads each template already
[rendered by the platform](/concepts/states#rendered-templates) — every body as jq text, the
input programs in the platform's dependency order — so one program may call a sibling by its
`tjq_<name>({…})` handle; the engine parses no template document of its own.

The prelude also emits a generic `attachment($state; $template)` locator: it yields the
attachment envelope, and `attachment($state; $template).data` the record subtree an `input`
program reads — so `attachment($state; $template).data | tjq_<name>({…})` is the explicit form
of a call whose `.` is that subtree.

When a program name is unique across the attachments in scope the engine emits the qualified
`tjq_<template>__<name>` — the template name slug-encoded `-`→`_`, so `my-tally` gives
`tjq_my_tally__<name>` — and the short `tjq_<name>` as an alias of it; when the name is shared
it emits only the qualified form (never a silent pick). An unknown name raises loudly. There is
no update/write callable in an expression — updates happen only through a binding's `updates`
([above](#binding-a-node-to-a-state)).

Two different programs never share a handle: a short handle can spell another template's
qualified one (template `t`'s program `a__x` and template `a`'s program `x` both give
`tjq_a__x`), and every such pair is refused loudly, naming both programs, wherever the prelude is
built — at a binding save (over every state the flow binds), at flow validation and route
binding, in `validate_jq`, at a run's start, and at an attach, declarations edit, or template
replace on a state a flow binds. Rename one program or template to resolve it.

A run builds its prelude once per distinct set of rendered attachment versions and every later
run on the same versions reuses it; an attachment change or a re-rendered template builds it
anew. A run also reads its flow's bindings once.

### Trace, declarations, and the effective schema

Three parts of a template are platform-owned and documented with the
[platform state store](/concepts/states#templates-and-attachments): under a **traced**
attachment the platform stamps a `_trace` object (`meta`, `run`, `turn`, `inbound`, `at`) on
every object a write touches — the engine supplies `meta: {node: <node id>}`; a template's
**declarations** carry static values a program reads as
`$declarations`, validated by their own schema and an optional `check` predicate; and the
platform composes each attachment's fragment into the state's **effective schema**, which
every write validates against.

### Binding scope

A binding's optional **`scope_expr`** is a boolean jq predicate evaluated **first**,
before the subject is resolved: `false` skips that state for the run — no injections and no
updates — and records a `binding_skipped` state-change event; a non-boolean raises; unset
means engaged. It means the same on every door and every node, and a door's `scope_expr`
wins over the preset's — see
[A binding's subject and scope](/concepts/states#a-bindings-subject-and-scope). This is how
one node, bound to several states, engages only the state its caller names.

### Shipped defaults

Babelfish ships no state templates of its own; a state template is a platform document, and a
resource that ships one (its schema, regimes, declarations, and template jq) registers it as a
[platform state-template seed](/concepts/states#templates-and-attachments) on the state store,
reconciled by content hash like any other seed.

## Upload — one door, two kinds

`POST /api/babelfish/upload` is one door for the flow engine's two self-describing document
kinds — the JSON's `kind` routes it. Both become presets. State and state-template documents
are uploaded from the platform [States screen](/studio/screens#states) instead, through the
platform's own [`/api/states`](/concepts/states#the-http-surface) doors:

* **`flow`** → a preset over the `flow` base tool, through the same in-process authoring path
  the preset HTTP doors use (create for a new name, a new active version for an existing one —
  earlier versions kept).
* **`node`** → the same, plus a palette **entry**: the preset carries a `palette-node`
  tag so it lists in the canvas palette, with an optional `folder` placing its card.

An unknown or missing `kind` is `422`; the response is `{kind, name}` (plus `version` for a
preset). The per-node bindings have direct routes too, keyed `(flow_name, node_id)`:
`GET /api/babelfish/bindings` (by `?flow=` or `?state=`),
`PUT/DELETE /api/babelfish/bindings/{flow_name}/{node_id}`,
`DELETE /api/babelfish/bindings/{flow_name}` (removes every per-node binding of a flow — the
Studio calls it when a flow is deleted — returning `{removed}`), and
`POST /api/babelfish/bindings/move`. Every one answers the same gated refusal (`503`,
`reason: states_unavailable`) when the flow states feature is off.

## Shipped defaults are files

The shipped defaults live as files beside the code: one JSON document per default (each with
its `kind`), a `retired.json` withdrawal manifest, and a `<name>.md` prose note beside each
document. A loader reads the folder at import and turns `node`/`flow` files into preset seeds, applied
**in-process** through the same seed appliers the upload door's writes reach — never by the
server calling its own HTTP. The document is the source of truth, and a default is told from an
operator edit by a content hash. A state-template document a resource ships is registered as a
platform state-template seed on the [state store](/concepts/states#templates-and-attachments).

## Run state

A run's state keeps of each node's inputs and outputs only what a later step reads, worked
out once per flow version over every scope — the top-level graph and every loop body:

* **Every value, in order** of `.outputs.<node>` / `.inputs.<node>` when an expression of the
  flow reads that node by name — a node's expression, run condition or result shaping, a
  holder's expressions, a conditional's and its branches', a loop's drivers, any On Error.
* **The newest value** when only the engine reads it: a node's inputs, a flagged result, a
  loop's output, branch routing.
* **Nothing** otherwise. A monitoring plugin still records every step's input and output.

An expression the engine cannot bound — one that reads `.outputs` or `.inputs` as a whole
(`.outputs | keys`, `getpath(...)`, `..`, a function over the channel) or uses a construct the
analysis does not cover (an inline `def`, an assignment, `label`, destructuring) — makes the
flow keep every node's full history. Validating or saving such a flow reports a
`state_read_unbounded` **warning** naming the expression; the flow still saves and runs.

The state also holds `node_visits`: per node visit, the step a monitoring plugin recorded it
as, for a holder what the visit did, and where in that step's record the node's result and
its evaluated inputs sit. A value one step writes for another node — a branch handing its
target an input, a loop publishing its output — is listed under that node too, naming the
step that wrote it. An On Error entry keeps the error and its context, not copies of the
run's channels; a loop's per-iteration results leave the state once its output is published.

A run records the stored format it was written in and what it keeps. A resume is refused —
the waiting caller receives FAILED with the reason — when the state was written in another
format, or when the flow was edited since to read something that run did not keep (the
message names it, for example `outputs.x (history)`). An edit that only removes reads, or
reads what the run already kept, resumes. Drain in-flight runs before upgrading to an engine
release that changes the stored format.

Large node values ride the checkpoint like any other value; on a store that copies channel values
into every checkpoint by default, and on any store when the deployment turns it on, the platform
stores each value above `LLM_PROVIDER_CHECKPOINT_SHARED_VALUE_BYTES` once per thread and
compresses values above `LLM_PROVIDER_CHECKPOINT_INLINE_COMPRESS_BYTES` (see
[Checkpoints and retention](/operate/checkpoints#large-values-are-stored-once)). `FLOW_REDIS_URL` serves the engine's run
markers and park index.

## Monitoring a flow

With a [monitoring plugin](/operate/observe), a flow run records each value once, in the
record of the step that produced it, and every other record holds a
[reference](/operate/observe#each-value-recorded-once) to it — the Resolved view assembles
the full value:

| Record | What it holds |
| - | - |
| `flow:input` | A fresh run's input: its arguments, its state documents and its warm-start fills. A subflow's input references the records its dispatching run's trace already holds. |
| `flow:attachments` | The attachment envelope a stateful run's expressions read as `$attachments` (each attached template's path, parameters and declarations), recorded at the fresh start and again at each resume, which renders it anew. A subflow whose expressions read the envelope its dispatching run recorded references that record; a subflow bound to other states records its own. A run whose states attach no template has none. |
| `LangGraph` (graph root) | The state a run segment, or one loop iteration, started from and ended with. A resumed segment's root holds the answer the run resumed with. |
| A node's step | The state the node received and what it wrote. Inside a loop, the step also names its node and its iteration path (`loop[1]/inner[0]`) and points at the values it wrote. |
| A router (`decided_route:`, `branch_route:`, `iterate_route:`) | The state it read and the route it chose. |
| A tool call | The call's arguments and result in full, over the call's window. |
| An expression (`expr:<node>`, `foreach_expr:<node>`, …) | A sub-step of its node: the data and variables the expression read, and its result. A state document its node received is a reference to the record that holds it: `flow:input` or the step that last wrote the state; for a state the node re-read (`refresh_states`), the record that already holds it — the `state:<name>` event of that read when the read brought a document the trace did not record. The attachment envelope it read is a reference to the `flow:attachments` of the start or resume its run — or its dispatching run — runs in. |
| `flow:result` | The run's final state and the result it returns, under the run's own trace. On a failed run the step carries the failure (level ERROR, the error text the caller receives) and the error envelope; the flow-level `on_error` handler's expressions are its sub-steps and the handler's tool call is a tool call of the run. A run has one `flow:result`: when shaping or checking the result fails, that same step ends at ERROR. |

A run's node popup reads a node's result and inputs through these records. Without a
monitoring plugin nothing is recorded, and the [run state](#run-state) keeps only what a later
step reads.

## Checkpoint retention and durability

A run's pause/resume memory lives in its checkpointer, and the platform owns how long it
lives — see [Checkpoints and retention](/operate/checkpoints). A flow run marks its own
session thread finished at its terminal (success, error, stop or abort — never at a pause),
together with every [agent session thread](#agent-session-continuity) it owns (a
`session_thread` template that contains `{flow_run_id}`), and takes them out of the finished
set when a run, a restart, a resume or a step starts on the session. The platform's
`sweep_checkpoints` removes a finished thread after
`LLM_PROVIDER_CHECKPOINT_RETENTION_FINISHED_MINUTES` and any other one after
`LLM_PROVIDER_CHECKPOINT_RETENTION_WAITING_MINUTES`, and spares a session whose latest
checkpoint still holds a pending interrupt — a parked run, whatever its age. A flow may
declare shorter values for its own runs (`config.checkpoint_retention`, see
[How a run runs](#how-a-run-runs-tool-calls-loops-and-abort)). The platform may still
deliver an ask's answer or expiry up to its redelivery horizon (`INTERACTIONS_IDLE_TTL_SECONDS`,
default 1 day) after the ask's deadline, so an async ask must carry a deadline at least that
long before the waiting retention runs out (with the defaults, within 6 days); one without a
deadline, or past that point, is refused loudly at suspend
(`AsyncParkExpiryBeyondRetentionError`). An answer that still finds the run's checkpoint gone
is answered failed with `ResumeCheckpointGoneError`. A holder that parks on its held call (a
send-up caller ask, or a held flow's own park) parks under the latest deadline among the held
call's open asks, so the same bound applies to it.

> [!NOTE]
>
> `FLOW_CHECKPOINT_RETENTION_DAYS` and `POST /api/babelfish/checkpoints/prune` are gone: the
> platform's two retention values and its `sweep_checkpoints` operation replace them. The engine
> owns the `FLOW_` prefix, so a deployment that still sets `FLOW_CHECKPOINT_RETENTION_DAYS`, or
> any other name under `FLOW_` the engine does not read, is refused at boot and on every settings
> write, naming it.

| Variable | Default | Effect |
| - | - | - |
| `FLOW_CHECKPOINT_DURABILITY` | unset | LangGraph's durability mode for every graph invoke: `sync`, `async` or `exit`. Unset leaves LangGraph's default (`async`). |

`sync` writes a step's checkpoint before the next step runs; `async` writes it while the
next step runs. `exit` writes only when the graph stops — at a pause (a tool call, a tool
that parks, a holder hand-over) or at the run's end. Under `exit` every step since the last
pause is persisted only at the next pause or the end, so a crash in between re-runs all of
those steps on recovery.

## Agent session continuity

By default every agent a runnable invokes gets a fresh agent thread per call. A
runnable may instead opt into **per-node session continuity**, keying that node's
agent runs to one retained session so memory carries across successive runs of the
node. The key is a plain-string template — placeholders for the flow-run id and the
node's raw id are substituted at run time, and the engine always forces the
reserved `flow:` prefix. Clearing the key in Studio resets it to the default template
`flow:{flow_run_id}:{node_id}`; a bare `flow:` would be one thread shared by every such
node in every run, so clear **Keep agent session across loops** instead to turn continuity off. Because the key is keyed on the raw node id it is stable
across iterations, so inside a sequential loop each iteration resumes the previous
iteration's agent thread; a parallel loop, which would drive the same key
concurrently, is rejected at build time. Real carry-over needs a
checkpointer-backed agent — a memoryless agent still runs but remembers nothing.

## How it plugs in

It installs like any other plugin: it registers its **Flows** page and the API
behind it under its own route mount, and integrates with the Studio the same way
every plugin does.

The bundle is committed inside the distribution, so installing it needs no
JavaScript toolchain on the server. The plugin ships its own HTTP API under its own
route mount and claims no backend — see [Studio plugins](/studio/plugins) for how the
Studio loads a plugin bundle and pins it.

## Organizing flows

Because a flow is an ordinary tool, it organizes through the platform's
[tool-organization overlay](/concepts/tool-organization) — the same folders,
display names, tags, and visibility that apply to any tool. The Flows page renders
that overlay directly:

* **Folders and breadcrumbs.** The page is a current-directory explorer: a
  breadcrumb, the folder's subfolders, then the flows filed there, with unfiled
  flows at the root.
* **Display names and tags.** Each flow shows its display name (its real tool name
  stays visible) and is filtered by its merged tags — a flow's plugin-native
  `babelfish` tag unioned with your editable user tags. A tag filter and a search
  box narrow the list. A tool's display name from that same overlay also surfaces
  inside the flow editor: a tool node's canvas label shows it, the node-editing
  tool pickers show it with the raw name kept visible, and the run popup and
  history inspector show it with the raw name in parentheses.
* **List or card view.** A toggle switches between a compact list and a card grid;
  the choice persists per browser.
* **Per-flow editing.** A flow row edits its display name, tags, and folder in
  place. Hiding a tool is centralized on the [Studio Tools
  screen](/studio/screens), not here — the Flows page manages everything except
  visibility.

The Flows page derives its entire view state — the open flow, the current folder,
open dialogs, and the active filters — from the URL, so a flow is bookmarkable and
shareable and the browser's back button works. A link to a flow that no longer
exists renders a loud not-found card rather than a blank editor.

## See also

* [Babelfish on tai42.ai](https://tai42.ai/babelfish) — the product, its pricing, and its terms.
* [Visual jq in flows](/babelfish/jq-editor) — the flow field's Inline/Template tabs and what each jq field seeds the editor with.
* [The jq editor](/studio/jq-editor) — jq-studio, the platform's open-source, built-in visual jq editor.
* [Studio plugins](/studio/plugins) — how a plugin contributes a Studio page.
* [Presets](/concepts/presets) — the versioned wrap a saved flow becomes.
* [Tool organization](/concepts/tool-organization) — the folders, display names, tags, and visibility a flow rides.


# Visual jq in flows
Source: https://docs.tai42.ai/babelfish/jq-editor

How the flow editor authors every jq expression through the platform's built-in visual jq editor.

Every jq expression a flow carries — a node's expression, a branch or loop
condition, a binding's injection or update jq — is authored in one field two ways: by typing
jq into the field's resting text control, or in a **visual editor**, opened from that
control, that draws the expression as a small, editable node graph and writes it back
as jq. The wire always carries the jq text.

That visual editor is not a flow-only thing and not a plugin you install. It is
[**jq-studio**](/studio/jq-editor) — the platform's open-source, built-in jq editor.
The [Studio SDK](/reference/studio-sdk/index) re-exports its `JqField` component, the
Studio host injects the design system and installs the evaluation worker, and the
flow editor renders that field directly. The same editor serves every jq field on
every Studio surface — a host field, another plugin's field, a flow's field — with
nothing to register and no gating.

> [!NOTE]
>
> The editor itself — its node vocabulary, the faithfulness guarantee, the theming
> contract, and the worker model — is documented with [jq-studio](/studio/jq-editor)
> and in its [open-source repository](https://github.com/tai42ai/jq-studio). This page
> covers what is specific to authoring a **flow**: the field's tabs and what each field
> seeds the editor with.

## Inline or Template

A jq field in the flow editor is a two-tab control — **Inline** and **Template** —
and the two are mutually exclusive: the wire carries exactly one.

* **Inline** is the SDK's `JqField`: a resting text control holding the jq, plus a
  **Visual editor** button that opens the visual canvas in a modal dialog. Edit the
  jq as text in the control, or open the dialog to build it as a node graph; on save
  the dialog writes the jq back to the same control. A `description` and an `error`
  helper slot render under the control, wired to it for screen readers.
* **Template** picks a stored [template](/concepts/storage-and-resources) and edits
  its kwargs through a schema-assisted form.

The active tab follows the draft: a field that already holds a template opens on
**Template**, otherwise on **Inline**. There is no separate "Editor" tab and no
auto-open of the canvas — the visual editor is always reached from the Inline
control's Visual editor button. Switching tabs is a mode change that clears the mode
you leave, after a confirm when it holds data.

Inside the visual editor, a loaded expression is drawn as a graph **only** when it
round-trips faithfully back to your exact jq. An expression the editor cannot draw
keeps your text verbatim and shows it with a neutral notice — your jq is never altered
— and the editable canvas is then reached only through an explicit **Start empty**.
That fallback lives inside the dialog; it is not a tab. See
[the jq editor](/studio/jq-editor) for the canvas itself.

## What each field seeds

Every jq field follows one rule for what it reads: **`.` holds only the data the
expression is about, and everything the platform adds beside it — the state
documents, the run identity, the loop context — arrives as a named jq variable**
([the platform-wide rule](/concepts/jq-variables)). So each field names what `.` is
at its site, and the editor's **Test** panel seeds a sample of that shape plus a
skeleton for each variable the site binds; where the engine exposes a matching
validator, the **Validate** action checks the same shape server-side:

* a node **expression** and a **conditional** or **branch** condition see the **node
  envelope** — the run's inputs and the upstream nodes' outputs, with this node's
  `.result` still null (a condition must return true or false);
* an **On Error** condition or expression sees the **error envelope** — the failed
  node's error on `.upstream_outputs` (`.error`, `.error_type`, `.error_kind`,
  `.additional`);
* the flow-level On Error's **Reply** sees the same error envelope, with the handler's
  outcome under `.upstream_outputs.additional` (`.handler_result`, or `.handler_error` when
  the handler failed), and must return text or `null`
  ([the participant reply](/babelfish#the-participant-reply-on-a-failed-run));
* a node's **return expression** sees the narrow **return namespace** — only
  `.result`, `.outputs`, and `.flow_graph_kwargs`; here `.upstream_outputs` is a
  **hard build error**, not a null;
* a binding's **input injection** jq runs after the node's input is assembled, before the node runs: a
  template `input` program sees the **record** (`.` is the subject's document at the
  attach path) with its declared `params` bound as the single object `$params`; a
  **custom** injection reads the bound **record** as `.` with `$input` the node's
  input so far, and its value is placed into the input at the injection's `into`
  field;
* a binding's **update** jq runs after the node completes and reads the node's
  **output** as `.`: a template `update` picks a named update program and shapes its
  declared input through an **adapter** (`.` the node output, `$input` the run input),
  while a **custom** update reads `.` the node output with `$record` the bound record
  and `$input` the run input and returns the template-relative **op batch**
  (`[{op, path, value}]`), where a per-op compare-and-set guard rides an op as
  `{path, expected}`;
* an update's **op-id** jq reads the node's **output** as `.` with `$input` the run
  input, and returns the key the write dedupes on;
* a binding's **subject** and **scope** expressions see the bare **flow inputs** document
  (`.` is `flow_graph_kwargs`, no envelope; `scope_expr` must return true or false);
* a **holder** node's **Cancel**, **Resume**, **Start**, and **warm-start** jqs see the
  **node envelope** with the held target's parked interactions bound as `$parked`;
* a loop's **`while` condition** sees the **node envelope** with `$iterate` present —
  `$iterate.item` is always null there, while `$iterate.prior_outputs` holds the
  per-iteration results the condition tests;
* a loop's **`foreach` expression** and a string loop **`count`** see the **node
  envelope** — for a `foreach` driver `$iterate` is the *enclosing* loop, not this
  one; a `count` runs jq only when the count is a string (a literal number bypasses
  it);
* a **map item argument** sees the **loop-body envelope**, where `$iterate.item` is
  the current item (never null here) and `$iterate.iteration` its zero-based position.

In every envelope, `.outputs.<node>` and `.inputs.<node>` hold a node's results in order,
newest last, for each node some expression of the flow names there; the run state keeps no
history of a node no expression reads that way (see [Run state](/babelfish#run-state)). An
expression that reads `.outputs` or `.inputs` as a whole — `.outputs | keys`, `getpath(...)`,
`..`, a function over the channel — or uses a construct the engine does not analyse (an inline
`def`, an assignment, `label`, destructuring) makes the flow keep every node's full history;
**Validate** reports it as a `state_read_unbounded` warning naming the expression, and the
flow still saves and runs. At run time each expression receives only the `.outputs` /
`.inputs` entries it names (a channel it reads as a whole, it receives whole), so its result
is the same, and its evaluation's trace record shows just those entries.

## The variables beside the input

Beside `.`, every flow jq binds the run's context as named variables, reachable
anywhere in the expression — inside a `map(...)` or `select(...)` too, where `.` is
rebound. The editor lists them on each field and seeds a sample for each in the Test
panel:

| Variable | What it holds |
| - | - |
| `$states` | The run's committed state documents, read as `$states.<name>.<field>`; null on a stateless run. |
| `$run` | The current run's identity — `$run.id` the session id, `$run.epoch` the state-mint epoch (null before one is sealed). |
| `$iteration` | The enclosing loop's zero-based position (0 outside a loop). |
| `$iterate` | The enclosing loop context, or null outside a loop; inside a body `$iterate.item` is the current item and `$iterate.iteration` its position. |
| `$attachments` | The attachment envelope the template `attachment(...)` locator reads. |
| `$current_user` | The calling user's id, or null for an anonymous caller. |

A **holder** node's start, cancel, resume and warm-start jqs add `$parked` — the
parked interactions on the held target, a list of `{id, status, …}` (status `asking`,
`running`, `finished`, or `failed`). A **state-binding** jq adds `$input` (the run
input) and, on a custom update, `$record` (the subject's committed record). A read of
an **undeclared** variable is a compile-time refusal at save, never a silent null. A
call to a template jq (`tjq_<name>({…})`) is checked at save against the templates
attached to the flow's bound states where the flow is validated by name (the editor's
save, a route bind), and admitted on a preset write, which carries no environment; a
run where the template is not attached refuses it loudly. The names the platform binds
cannot be rebound with `... as $name`.

## Autocomplete from a state's template jq

A jq field that can reach a bound state offers autocomplete from the
[template jq](/babelfish#state-templates) of the templates attached to that state.
Typing offers each `purpose: "input"` template jq by name and inserts its call
handle — `tjq_<name>({…})`, or `tjq_<template>__<name>({…})` when a name is
shared across the state's attachments — so an expression reads a template's value
through the prelude without hand-writing the def. The suggestions come from the
served [state-template document](/babelfish#state-templates)'s `template_jq` for the
bound state's templates, so they track whatever the attachment declares.

## See also

* [jq variables](/concepts/jq-variables) — the one rule for a jq's input and its named variables, across every platform surface.
* [The jq editor](/studio/jq-editor) — jq-studio, the built-in editor the flow editor renders, and how to embed it in your own app.
* [The visual jq editor](/babelfish#the-visual-jq-editor) — the editor as it appears in the flow canvas: its node vocabulary, the faithfulness guarantee, and the editor shell.
* [Babelfish Flows](/babelfish) — the flow engine whose fields author through this editor.
* [Author a Studio plugin](/studio/plugins#the-built-in-jq-editor) — the SDK re-export every plugin field renders the same editor from.


# Flows editor
Source: https://docs.tai42.ai/babelfish/studio

The Babelfish Flows page in the Studio: the flow browser, the node edit panel, the Router card and its dispatch modes, the classifier card, the visual jq editor, and per-node state bindings.

The **Babelfish Flows** page is the flow engine's own editor in the Studio, contributed
by the [Babelfish Flows](/babelfish) plugin (see [the Studio screens](/studio/screens#flows)
for how a plugin contributes a page). The page is a browser for your saved flows that mirrors
the Tools screen's organization: it navigates
[folders](/concepts/tool-organization) with a breadcrumb, toggles between a list
and a card view (the choice persists per browser), and filters the list with a tag
filter and a search box. Each flow row edits its display name, tags, and folder in
place; hide management stays centralized on the Tools screen. The list carries an
**Attachments** column — one badge per kind of thing that references the flow (a
schedule, a hook, a route, an extension, or a bound state) — reserved at a fixed width from
first paint across its loading, empty (a muted em dash), and populated (the kind chips) states,
so a resolved attachment index never re-lays out the list. The whole view — the
open flow, the current folder, dialogs, and the active filters — is derived from
the URL, so a flow is bookmarkable and the back button works; opening a link to a
flow that no longer exists renders a loud not-found card, never a blank editor.

## The node edit panel

Selecting a node on the canvas opens a **tabbed edit panel** — **Settings**,
**Input**, **Output**, **State**. Settings is the per-kind configuration form and
its Update-node action; a fan-in or loop node's Settings also carry the barrier's
[wait knobs](/babelfish#node-waits) (wait mode and the timeout give-up pair) and,
where the flow binds states, the opt-in
[state-refresh](/babelfish#refresh-opt-in-state-re-read) toggle. Input and Output are
read-only: they render the node's
declared input and output schemas — with the node's outcomes surfaced on Output —
so a node's contract is readable in build mode, and each shows an empty state when
nothing is declared.

The Input tab also carries a **Receives from** block — *resolved by the engine after
edge transforms* — resolved live off the canvas as you edit: the inputs the engine
works out a node will actually receive at run time, which are its
[declared inputs plus the ones its incoming edges add](/babelfish#inputs-and-results).
Each is a chip, **solid** for a declared input and **outlined** (titled *from an edge*)
for one an edge derives, so what reaches a node beyond what it declares is visible at a
glance. The block draws its own loading and empty states and surfaces a loud alert when
the canvas cannot be converted to a graph or the engine cannot resolve it, rather than
showing stale chips.

![The Input tab of a loop node's edit panel: a Receives from block, resolved by the engine after edge transforms, with a solid seed chip for the declared input and an outlined producer chip for the edge-derived input, above an input-schema panel reading that no input is declared and the node derives its input from incoming edges.](https://mintcdn.com/tai42/5AiuMgG-vJFUF9vE/images/studio/resolved-inputs-light.png?fit=max\&auto=format\&n=5AiuMgG-vJFUF9vE\&q=85\&s=94d81f358b998e54efb52d2f08b015ad)

A loop node's Input tab: the Receives from block, its declared input solid and its edge-derived input outlined, above the node's declared input schema.

A scheduled node's Settings also carry an optional [**run
condition**](/babelfish#run-condition) — a jq predicate that gates whether the node
runs at all. A false condition *skips* the node: it does not execute, its output is
null, its status reads **skipped** in Run mode, and the flow continues past it (the
gate stops the one node, not the path). The field is absent on a node that runs only as
a Recovery, since such a node is dispatched directly and never scheduled. A runnable's Settings
also carry **Run after the reply** — the [`after_reply`](/babelfish#run-after-the-reply) toggle,
"Call the tool after the reply". With it on, the node's tool is called after the run has
answered; in Run mode the node settles with a clock glyph labelled **Node call runs after the
reply** and a muted ring, and its run popup shows the status `deferred`.

![A finished run on the canvas: the runnables warmup and answer settled with a success check, and the runnable later, set to run after the reply, settled with the clock glyph and a muted ring.](https://mintcdn.com/tai42/C97bEX4Y1-MJSgdV/images/studio/run-view-deferred-node-light.png?fit=max\&auto=format\&n=C97bEX4Y1-MJSgdV\&q=85\&s=8edaa80c8a3b001d4b15bff09a1655ed)

A finished run: the node set to run after the reply settles with the clock glyph and a muted ring.

When an agent node carries a [structured-output
schema](/babelfish#structured-agent-output), the Output tab renders that schema live
and its label reads **Output (structured)**. Editing that schema to **remove** a field
surfaces a non-blocking honesty note on the agent's Settings: static analysis scans the
flow for downstream jq that still reads the removed path off this agent
(`.upstream_outputs.<agent>.<path>`, including the flow-level On Error) and
names the references that would silently start resolving to null — it never blocks the
save (references built dynamically are, honestly, not detected). The State tab is the
node's [state binding](#state-bindings) — the shared binding editor, one per node — and
its tab label carries a live count of the states the node binds.

## The holder panel

A node that **calls another flow or an agent** — a Flow Call, a custom node, or an
agent — is a [holder](/babelfish#calling-another-flow-cancel-resume-start): it starts
that call, and can cancel or resume the call's own [parked
interactions](/concepts/asking-the-caller). Its Settings form is the holder panel,
whose controls read top to bottom:

* **Target.** A Flow Call picks its held flow or agent here, from a select scoped to
  saved flows, every registered agent and the presets over them — never a plain tool;
  each option is labelled with its kind (`(flow)` or `(agent)`). Every load state is
  drawn: the select disables with a "Loading…" placeholder while the registry is in
  flight, a load failure shows inline, and an empty target is a loud field error, so a
  placed-but-unconfigured Flow Call cannot apply. While the agents list is still loading
  the flows are offered and the agents are not yet listed; if it fails to load, the panel
  says so under the field — "Could not load the agents list, so agents cannot be picked as
  a target" — the flows stay selectable, and a holder already holding an agent keeps its
  target shown. Picking `tools_agent` (or a preset over it) turns the node into an Agent
  card; any other agent stays a holder with this panel. An agent card holds no Target
  picker — its target is the agent itself.
* **Cancel.** One jq over the [node envelope with `$parked`](/babelfish/jq-editor#the-variables-beside-the-input)
  that emits null, one parked-ask id, or a list of ids to cancel — a whole-chain
  cancel of each named call.
* **Resume.** One row per ask of the held call, each an id jq naming the parked ask
  and a payload jq carrying the answer to resume it with. Leave a row's payload empty
  to **take** the ask's resolved waiting outcome — a finished run's result, while a
  failed outcome raises; a payload jq giving null resumes with null.
* **Start.** The `start_expr` jq that shapes the held call's input (a holder has no
  plain expression input): absent starts the held target on the node input, a jq
  giving null starts nothing, and any other result merges over the resolved node input
  (a non-dict result wrapped as `{input: …}`), the expression's keys winning on
  collision. A Flow Call
  nests its **warm-start** rows inside Start — each names a node of the held flow and
  a jq whose value pre-fills that node's output, so the held run skips producing it; a
  row whose jq gives null runs that node normally. An agent holds no flow graph, so it
  shows no warm-start rows.
* **Send the ask up to my caller.** A switch that, instead of routing a caller ask to
  an ask exit, parks it as a nested park and hands it up to this flow's own caller
  unchanged.

Every jq slot reads through the same Inline / Template control the other editor jqs
use, so a stored template id shows and survives an open-edit-save.

**The ask exit.** When the holder's target **can ask its caller** and the send-up
switch is off, the card grows an extra exit handle labelled **ask** on its outcome
edge — the node a caller ask routes to. Unwired it renders as a dashed ring and the
save gate blocks with a "wire the ask exit" message; wired it is a solid ring. A
holder that can ask its caller needs either this exit or the send-up switch, or a
caller ask has nowhere to go.

## Ask and expiry controls

A runnable that calls the [`ask`](/concepts/interactions) tool carries a small ask
face over its own kwargs — the raw JSON stays the single source of truth. **To**
picks the recipient, **user** or **caller**; **mode** picks sync or async delivery;
an async ask carries a **deadline**; and **On expiry** says what the run does when
nobody answers in time — **end the run** (the default) or **resume with the expired
marker**. A `caller` ask always resumes asynchronously, so its Sync option is hidden
and it runs async; an async ask requires a deadline, checked on apply.

A **held** ask — an ask flow called through a holder — has no On-expiry control at
all. Its expiry is derived from the [outcome wiring](/babelfish#expiry-in-a-flow):
wire the holder's **expired** outcome downstream and the ask resumes on expiry so
that branch runs; leave it unwired and expiry ends the held chain. The two never
disagree, because the derivation, not an authored field, owns it.

## The test panel's caller asks

Running a flow in-page against a **subject** surfaces the caller asks waiting on that
subject. The run controls carry a subject input — a target kind, target name, kind,
and key — threaded into the run and every interaction call; left empty, no subject is
sent. While a run sits suspended with caller asks outstanding, the panel lists each
one — its question, its payload, and who asked it — with a payload editor and three
actions: **Resume** the ask with the edited payload, **Take** its resolved waiting
outcome (no payload — a finished run's result, while a failed outcome raises), or
**Cancel** it. Each action re-reads the run's outcome: a result ends the loop, fresh
asks re-render the list, a re-park on user asks alone ends it with the parked note,
and a cancel that started nothing drops only the cancelled ask. A cancel ends the whole run
the ask belongs to, and nothing is sent to the person asked: the run's other asks close with it,
and acting on one of them shows **That ask is no longer waiting — reload the run.** A
node timeline shows what each holder node did — the calls it started, resumed, took,
or cancelled, and any warm-filled node — so a held run's decisions are readable as it
progresses.

![The test panel's caller-ask controls: resume, take and cancel on each waiting ask.](https://mintcdn.com/tai42/C97bEX4Y1-MJSgdV/images/studio/run-panel-ask-light.png?fit=max\&auto=format\&n=C97bEX4Y1-MJSgdV\&q=85\&s=e29f05c5c35b9e82072cfcda8f71be53)

The test panel's ask controls: resume, take and cancel.

## Schema-aware run results

When you run a flow in-page, the run panel and each node's run popup render results
**schema-aware**. Where a node declared its output shape — an agent's structured-output
schema, or a preset's (or the whole flow's) output schema — the actual result
renders as a **labeled, typed display** keyed off that schema: the schema's titles as
field labels, its descriptions as captions, enum values as chips, nested objects as
sections, and a declared array as a list of its typed items. The view stays honest about the data: value keys the schema does **not**
declare are never hidden — they render as an appended raw-JSON remainder — a declared
field absent from the value shows a muted dash, and a value that does not match the
schema's shape at the top level falls back to the plain JSON tree with a small note
rather than a crash. A per-instance **Raw** toggle flips the whole view to the plain
tree, so the underlying data is never more than one click away, and a flow (or node)
that declares no output shape keeps the plain results tree throughout.

## Values the run state does not keep

A run keeps of each node's inputs and outputs only what a later step reads (see [Run
state](/babelfish#run-state)). A node's run popup shows each section from the first place that
has it:

* **Kept in the run state** — the node's newest value, shown directly.
* **Recorded by a monitoring plugin** — the popup reads the value from the step that recorded
  it: a muted *Loading this step's recorded data…* line with a spinner, then the value exactly
  as a kept one. When the value cannot be read yet, *Could not load this step's recorded data:*
  and the reason show with a **Retry** button.
* **Not written for this node** — the section is hidden.

With no monitoring plugin, a popup missing a value says once, under its sections: *Values that
no later step reads are not kept in the run state. A monitoring plugin records every step's
input and output.*

![A node's run popup showing its output and the note that values no later step reads are not kept in the run state.](https://mintcdn.com/tai42/mNH8SxuFXcGoykam/images/studio/run-popup-kept-light.png?fit=max\&auto=format\&n=mNH8SxuFXcGoykam\&q=85\&s=bea197d192aa7bc5e5ddb289a2d1794a)

A result node's popup: its kept output, and the note for the input the run state does not keep.

![A node's run popup showing Could not load this step's recorded data: Run span not found, with a Retry button.](https://mintcdn.com/tai42/mNH8SxuFXcGoykam/images/studio/run-popup-recorded-error-light.png?fit=max\&auto=format\&n=mNH8SxuFXcGoykam\&q=85\&s=35267282b0494d169c68b7e46d9e69b1)

A node's popup opened before its step was ingested: the read's error with Retry.

![A node's run popup showing its input and output loaded from the recorded step, with no note.](https://mintcdn.com/tai42/C97bEX4Y1-MJSgdV/images/studio/run-popup-recorded-light.png?fit=max\&auto=format\&n=C97bEX4Y1-MJSgdV\&q=85\&s=bdd3ed86136237367119794422894918)

With a monitoring plugin: the input and output read from the step that recorded them, shown as kept values.

A node inside a loop body shows one row per iteration — from the running loop's results, the
loop's published output, or, with a monitoring plugin, the recorded body steps under each
finished iteration (rows of a nested loop's node read *Iteration 0 › 1*). Before any iteration
finishes the popup says *No iteration of this loop has finished yet.*; a node that ran in none
says *This node did not run in any finished iteration.*; with no monitoring plugin it says
*Per-iteration detail for this node is not kept in the run state. A monitoring plugin records
it.*

![A loop body node's run popup listing one row per iteration with each iteration's output.](https://mintcdn.com/tai42/mNH8SxuFXcGoykam/images/studio/run-popup-loop-rows-light.png?fit=max\&auto=format\&n=mNH8SxuFXcGoykam\&q=85\&s=3731c93d4c3f03382519a61aee709570)

A loop body node's popup: one row per iteration, from the loop's kept output.

![A loop body node's run popup saying its per-iteration detail is not kept in the run state and a monitoring plugin records it.](https://mintcdn.com/tai42/mNH8SxuFXcGoykam/images/studio/run-popup-body-note-light.png?fit=max\&auto=format\&n=mNH8SxuFXcGoykam\&q=85\&s=f388647077863a9ae32c652b7367631b)

An interior loop body node's popup with no monitoring plugin.

![An interior loop body node's run popup listing three iteration rows, the second errored with its failure.](https://mintcdn.com/tai42/sg6A0m6Ni9k38ftx/images/studio/run-popup-body-rows-light.png?fit=max\&auto=format\&n=sg6A0m6Ni9k38ftx\&q=85\&s=75f97734be67fb5cd6d1177d766b0e22)

An interior loop body node with a monitoring plugin: one row per iteration from the recorded body steps, one errored.

![A nested loop body node's run popup listing rows Iteration 0 › 0 through Iteration 1 › 1 with each value.](https://mintcdn.com/tai42/onrIOtDUJGvfcZAm/images/studio/run-popup-nested-rows-light.png?fit=max\&auto=format\&n=onrIOtDUJGvfcZAm\&q=85\&s=12e36d29d54550bc3249391929126345)

A nested loop's body node: its rows labelled Iteration i › j.

## The Router card

The [**Router**](/babelfish#routing-on-a-verdict) card carries its own edit surface:
the **kinds** it classifies into, optional **turn-level output fields** that describe
the whole classified turn (each a top-level output beside the kinds), the author's
system prompt, a **routing** mode — every match (the default, firing every matching
route) or first match (the first matching route wins) — and a **routes table** listing
every wired route with its flavor, its **key**, condition, guard, target, and a
per-route **On Error** switch. A route's target is
the edge drawn from its chip on the card, so the table shows it rather than picking it.
Under first match the table also orders the rows — the row number is the evaluation
priority — and a row reorders by [dragging its grip or stepping its move
buttons](/babelfish#the-routes-table); the table's advisory notes flag a row an earlier
one already covers, without ever blocking the save. Each route's [key](/babelfish#route-keys) names its branch in
the saved flow and in traces, and a route's [On Error switch](/babelfish#per-route-on-error)
gives that route its own On Error, covering a [**runnable**, **agent**, **flow call**, or **custom node**](/babelfish#per-route-on-error) the route leads to.

A segmented **Decided by** control at the top of the form chooses who judges the kinds
— **LLM agent** (glossed *reads, extracts items, can loop*) or **Classifier model**
(*fast yes/no per kind, with a probability*), the two backings the [router
page](/babelfish#decided-by) describes. The Router entry is offered whenever the host
registers **either** backing tool; on a server with neither it is disabled with the
reason **Requires the tools\_agent or classify tool**. Each option is disabled on its own
when its tool is missing (**Requires the tools\_agent tool** / **Requires the classify
tool**), and the classifier option is also disabled while Loop, per-kind fields, or
turn-level fields are set — the control names what to clear first, so switching backing
is never a silent drop.

Under the **Classifier model** backing the form drops the agent-only controls: the
**system prompt** is hidden — a classifier reads state and its questions, not a prompt,
and the prompt draft is kept in the session so switching back to the LLM agent restores
it — **Loop** is disabled with *Loop needs extracted items. Only the LLM agent extracts
them.*, and each kind's description field asks *When is this kind a yes?*. In their place
the card shows a **Yes when the probability is at least** threshold field (0 to 1, step
0.05, default 0.5) and a classifier **Model** section — a **Provider** and a **Model**
input, the Provider glossed *Leave empty to use the host's default classifier provider* —
replacing the LLM provider/model/temperature section. A kind route then fires when its
yes-probability reaches the threshold.

![The Router Settings form with the Decided by control set to Classifier model, the yes-probability threshold, and the classifier Model section.](https://mintcdn.com/tai42/XPCQA-vQLG1IjDAV/images/studio/router-decided-by-form-light.png?fit=max\&auto=format\&n=XPCQA-vQLG1IjDAV\&q=85\&s=f19738c703297481fd0e8c094a5b714c)

The Router form under the Classifier model backing: the Decided by control, the threshold, and the classifier Model section.

On the canvas a classifier-backed router carries a **classifier** face badge in place of
the loop badge (Loop cannot apply there); an LLM-agent router keeps its loop badge when
it loops.

![A classifier-backed Router card on the canvas showing its classifier face badge.](https://mintcdn.com/tai42/C97bEX4Y1-MJSgdV/images/studio/router-classifier-canvas-light.png?fit=max\&auto=format\&n=C97bEX4Y1-MJSgdV\&q=85\&s=094b1ea1b6682a666544ab777b7c13ad)

A classifier-backed Router on the canvas with its classifier face badge.

The card's **Output** tab renders the verdict schema: under the classifier, one yes/no
answer per kind — a `noul` probability keyed by the kind name — and under the LLM agent
the extracted-item schema with any turn-level fields. As on the [Classifier
card](#the-classifier-card), the classifier verdict schema is not saved into the flow, so
downstream reads of its per-kind probability stay untyped.

The **system prompt** is written one of two ways on the card's tabbed control:
**inline** (the Plain text tab) or pointed at a **stored template** (the Template tab). In
both modes the platform fills a `router_kinds` render variable with the [generated kinds
block](/babelfish#routing-on-a-verdict) — the classify instruction and the kind descriptions.
Inline, the editor appends `{{ router_kinds }}` after your prompt on save; with a stored
template, the template writes `{{ router_kinds }}` where the block should appear and supplies
its other variables through its kwargs. A kind's description is never parsed as template
markup — it rides as a value. A stored template must declare `router_kinds` in its schema —
the editor refuses one that does not — and the author's own kwargs may not use the reserved
names `router_kinds` or `_tai_locale`. Locale variants do not apply here. A router saved by an
earlier editor version, its kinds block written into the prompt text under a heading, is
re-saved once: open it, trim the stale generated text from the prompt, and save.

The card also carries one **Dispatch** control, set once for the whole card — **Once**
(every matched chip continues the flow along its line) or **Loop** (each chip's line starts
a body that runs once per classified item, sequentially or in parallel with an optional
max-concurrency cap, or repeatedly while an authored jq condition holds under a max-runs
safety cap). Under Loop the card grows a **result** chip through which the collected output
of every chip leaves. The chips look and connect the same in both modes; the modes are
documented on the [router page](/babelfish#dispatch-once-or-loop).

## The classifier card

The **Classifier** card judges its input against typed questions — the
[classifier](/concepts/classifiers) model type as a flow node (see [Judging with a
classifier](/babelfish#judging-with-a-classifier)). It sits in the palette's
**Agentic** group between Sub-flow Start and Router, drawn with the **Scale** icon and
a **Judge** badge, and glossed "Asks typed questions about its input — yes/no, pick
one, rate — and returns probabilities." The entry is enabled only when the
[`classify`](/guides/standard-toolbox#judge-state-with-classify) tool is registered; on
a server without it, the entry is disabled with the reason **Requires the classify
tool**.

![The palette Agentic group with the Classifier entry, its Judge badge and gloss.](https://mintcdn.com/tai42/XPCQA-vQLG1IjDAV/images/studio/classifier-palette-light.png?fit=max\&auto=format\&n=XPCQA-vQLG1IjDAV\&q=85\&s=14bccb419a7470ecd959bbf2436f0e45)

The Classifier entry in the palette's Agentic group.

![The Classifier palette entry disabled with the reason Requires the classify tool.](https://mintcdn.com/tai42/XPCQA-vQLG1IjDAV/images/studio/classifier-gate-light.png?fit=max\&auto=format\&n=XPCQA-vQLG1IjDAV\&q=85\&s=f44e63e48708a260a9ae34d238bd7848)

The Classifier palette entry disabled when the classify tool is not registered.

On the canvas the card carries routing-in, routing-out, and error handles, and a
compact band of one **chip per question** — a type glyph and the question's key. The
band shows up to four chips at rest with the rest folded as "+K more" and every chip
when the card is selected; the chips are display only and draw no handles.

![A Classifier card on the canvas showing its per-question chip band.](https://mintcdn.com/tai42/C97bEX4Y1-MJSgdV/images/studio/classifier-canvas-light.png?fit=max\&auto=format\&n=C97bEX4Y1-MJSgdV\&q=85\&s=94313dbdd930998d9046d4621596565f)

The Classifier card on the canvas with its per-question chip band.

![A selected Classifier card with all its question chips shown.](https://mintcdn.com/tai42/C97bEX4Y1-MJSgdV/images/studio/classifier-selected-light.png?fit=max\&auto=format\&n=C97bEX4Y1-MJSgdV\&q=85\&s=60f192f98836222a1485246a13ac44b4)

A selected Classifier card revealing every question chip.

Its Settings form reads top to bottom: **Name**, **Description**, the **Questions**
table, **Input expression**, **Model**, **Run condition**, and an **Advanced** toggle
that reveals the standard runnable surface and the read-only round-trip carriers.

Each row of the **Questions** table has a **Key**, a **Type** segmented control —
**Yes/No · Pick one · Rate** — an **Instructions** textarea, and the type's own
criteria editor:

* **Yes/No** — two optional one-line inputs, **Means yes when…** and **Means no
  when…**.
* **Pick one** — an options list, each option a **label** and a **description**, added
  and removed in place.
* **Rate** — an ordered list of **levels** (two or more), added, removed, and moved to
  set the rubric's order.

Validation is inline per row, and the apply gate blocks Update on any invalid row —
the card needs at least one question to save.

The **Input expression** field is the same **Inline / Template** control every other
editor jq uses: the Inline tab takes a jq and helps with "Must return an object with
a `state` key — what the classifier reads. Empty: the whole upstream input is judged.";
the Template tab points the slot at a **stored template** by id, with its kwargs edited
beside it. A stored reference lowers onto the runnable verbatim and folds back into the
card on load, so a classify node authored the template-and-kwargs way is a Classifier card
like any other. The **Model** section is a **Provider** and a **Model** text input; the
Provider field's helper reads "Leave empty to use the host's default classifier provider"
— so an unset pair runs on the host's configured classifier.

![The Classifier Settings form with the questions table, input expression and model fields.](https://mintcdn.com/tai42/C97bEX4Y1-MJSgdV/images/studio/classifier-form-light.png?fit=max\&auto=format\&n=C97bEX4Y1-MJSgdV\&q=85\&s=29ac2df1026a417e482755090216a2e3)

The Classifier form: the questions table with the three editors, the input expression, and the model.

The **Output** tab renders the response schema **generated from the card's
questions** — one answer per question keyed by its key — so the answer shape is readable
in build mode and run mode renders the result against it. The schema is not saved into
the flow: downstream reads of the answers stay untyped, as
[Judging with a classifier](/babelfish#judging-with-a-classifier) explains.

![The Classifier card's Output tab showing the generated answer schema.](https://mintcdn.com/tai42/XPCQA-vQLG1IjDAV/images/studio/classifier-output-light.png?fit=max\&auto=format\&n=XPCQA-vQLG1IjDAV\&q=85\&s=6a9dfc348a1ce6337129e818220fa754)

The Classifier card's Output tab showing the schema generated from its questions.

On save the card lowers to one runnable calling `classify` and folds back into the
single card on load. A saved runnable marked as a classifier but no longer calling
`classify` is shown as a **refusal** naming the mismatch rather than folded silently,
leaving the plain runnable visible.

## The updates half of the binding editor

A node's [state binding](#state-bindings) applies **updates** to a bound state after the
node runs, edited in the **Updates** list of the shared binding editor. Each update writes
one of two ways:

* a **template jq** the state's attached templates declare (`purpose: "update"`), picked
  from a select that lists each update program as `name — description`; the selected
  program's declared write paths show beside it as a `writes:` badge. The run applies its
  returned op batch — [keyed list ops](/babelfish#keyed-state-list-ops) and appends — under
  the attachment path. Because a named update jq never sees a tool's field names, an **adapter**
  form maps the node's output and the run input to the update jq's declared input — one row per
  declared key, each picking a field, a literal, or a jq, with a write-jq escape hatch for
  the whole adapter.
* a **custom jq** reading the node's output as `.`, with the bound record as `$record` and the
  run input as `$input`, returning the op batch itself, for a write the templates do not name.

An update may carry an optional **op id** for idempotency. The write-regime check runs at
save: a landing path outside the update's declared writes, or an adapter whose output misses
the declared input, is refused loudly. A save that writes a path another flow also writes
**succeeds** and surfaces a quiet, non-alarming note; a genuine write failure still renders
loudly. With the states store not configured, the binding surfaces self-hide rather than
erroring.

## Presets

The palette's **Presets** section manages a
[preset](/babelfish#presets) as a node: an edit control opens its flow
editor, a **+ New preset** action starts a fresh one, and a delete control
raises a guarded confirm that states the blast radius — the node leaves the palette
and any flow already embedding it keeps a dangling reference. When a node edit
removes an outcome value that wired callers route on, the make-a-node dialog shows an
**informational** warning naming the removed values and how many flows use the node
(their routes would go dead) — it never blocks the save. This inform-don't-block
convention is the editor's house style for changes whose impact lands on callers.

The one thing the make-a-node dialog **does** block on is a genuinely *invalid*
input-schema edit. The make-a-node dialog's input-schema editor nulls its buffer while
an edit is unparseable, and saving then would silently **erase** the schema — the right
outcome for a deliberate clear, the wrong one for a typo. So Save is disabled precisely
while the input-schema buffer is invalid (a bad shape, not an empty one), with an inline
"fix the input schema before saving" note; a cleared buffer reports valid and saves a
null schema as intended. This is a validity gate, distinct from the non-blocking
caller-impact warnings above.

## Message and expression slots

A **message** slot on the agent form is edited as a **Plain / Template** tabbed
control: Plain is a raw message textarea, and Template picks a stored
[template](/concepts/storage-and-resources) with a deep link to the file and a
collapsed preview of its first lines, editing its kwargs through a schema-assisted
form over the authoritative JSON. A jq **expression** slot — on the conditional,
branch, runnable, On Error, and agent forms — is instead an **Inline / Template**
control: the Inline tab is the [visual jq editor](/babelfish#the-visual-jq-editor)'s
field (below), and Template is the same picker. In both, the inline value and the
template are mutually exclusive — the wire carries one, and switching between them
clears the mode being left after a confirm when it holds data. An invalid node that
carries **both** an inline message and a template opens on the Template tab with a
rescue note and a one-click "clear inline text" action, so the exactly-one-of rule is
fixable in place. A node with a return
result may carry a **return expression** (jq) that shapes the value it contributes
to the flow result, and a conditional's branch may be marked **pass-through** to
inject the conditional's single upstream output verbatim — which excludes a
post-route expression and a return. Settings the form does not model — kwargs an
API-authored or newer agent carries — are surfaced **read-only** so nothing an agent
persists is fully invisible, and are round-tripped untouched.

A jq field that can reach a bound state — a binding field, a node expression — offers
autocomplete from the [template jq](/babelfish#state-templates) of the templates attached
to that state: each `purpose: "input"` program by name, inserting its `tjq_<name>({…})`
call handle (`tjq_<template>__<name>({…})` when a name is shared across the state's
attachments).

## The visual jq editor

The **Inline** tab's field is the [visual jq editor](/babelfish#the-visual-jq-editor):
a jq text control with a **Visual editor** button that opens the canvas in a dialog,
where the expression is drawn as a small, editable node graph and written back as jq.
The dialog wraps a **Test** panel (run the jq against a sample seeded to the field's
input shape, plus a server **Validate** where the engine exposes one), a **live
readout** of the jq the graph currently serialises to, an **error summary** that jumps
to each problem, and a **Legend** of the node kinds and wire notations.
The [node vocabulary and its semantic hues](/babelfish#the-visual-jq-editor) — Input,
Value, Operator, Condition, Try/Catch, Call Function, Define Function, Comment — are
documented with the feature.

The editor draws a graph **only when it can prove that reading it back gives exactly
your expression**: a WASM oracle round-trips the graph and adopts it only when the two
behave identically. Otherwise the fallback is non-destructive — an expression the
editor cannot draw, or one whose graph would read back differently, keeps your text
verbatim and shows it as text with a neutral **"not shown here"** notice; nothing is
altered unless you explicitly **Start empty**. This keeps two questions apart — *is
the jq valid* and *can the editor draw it* — so only jq that genuinely fails to
compile raises the loud **"invalid expression"** alert, and valid jq the editor cannot
represent is never mislabelled as broken. On opening the dialog, a faithful expression
is drawn on the canvas; an unfaithful one shows the fallback, and the editable canvas
is then reached only through **Start empty**.

## State bindings

Flows bind to the platform [state store](/concepts/states) rather than a store of
their own, so declaring states, attaching templates, and browsing records all live on
the Studio's [States screen](/studio/screens#states). What the flow editor owns is the
binding: how each node reads and writes those states. Every node's edit panel carries a
**State** tab, and its binding is the [same editor](/reference/studio-sdk/index) the
platform's door screens use — shipped from the Studio SDK so a door and a node bind a
state the same way.

The editor attaches one or more states to the node. Each **state** card picks the
state and one or more **templates** (a template not yet attached is attached on save),
then a **Subject** expression (a full subject object or a bare key) and an optional **Scope**
predicate that gates the state for the run —
[the same on every door and node](/concepts/states#a-bindings-subject-and-scope).
Below the card, the **Inputs** list injects a value into the node's input before it runs —
each row a `purpose: "input"` [template jq](/babelfish#state-templates) (or a custom jq
reading the bound record as `.` with the run input as `$input`) and the input field it lands in — and the **Updates** list applies
a write after the node runs (the [updates half](#the-updates-half-of-the-binding-editor)
above). Every jq field autocompletes from the attached templates' template jq.

Where the node's tool is a registered preset that carries its own door binding, the editor
shows an advisory on any state both bind — *Overrides the preset's subject* — with the
preset's own subject shown as the read-only default beside it; the node's binding wins.
Every control rebuilds from the stored binding: an update's adapter form recovers each row
from the stored adapter jq, and a state or template the binding names but the server no
longer serves shows a **Template not attached.** error with the raw jq, never a blank
control. A refused save renders the engine's message verbatim.

## Upload

The flows toolbar carries an **Upload** action for a flow or node document with a `kind`,
reporting the uploaded kind and name in a status line and prompting when a file carries
no `kind`. State and state-template documents are uploaded from the
[States screen](/studio/screens#states) instead.

![The flows toolbar Upload action reporting the uploaded document's kind and name.](https://mintcdn.com/tai42/C97bEX4Y1-MJSgdV/images/studio/flows-toolbar-upload-light.png?fit=max\&auto=format\&n=C97bEX4Y1-MJSgdV\&q=85\&s=5bb3e3ab095e43757ff2e74fad9d6688)

The flows toolbar Upload action with its result line.


# Wiring an outcome by hand
Source: https://docs.tai42.ai/babelfish/wire-form

The wire form a wired outcome lowers to, so a hand-authored flow routes an outcome exactly as the editor does and earns the same expiry behaviour.

A node whose held call declares an **outcome** — one result field whose value is
one of a fixed set — offers one routing choice per value in the editor. Wiring a
value to a downstream node lowers to a plain routing shape on the wire: the node
itself, unchanged, **plus one hidden conditional** that reads the held call's result
at a pinned path and routes each wired value to its target. This page is that wire
form. Author it by hand and your flow routes an outcome exactly as the editor's flow
does — and an ask's [expiry](/babelfish#expiry-in-a-flow) is derived the same way.

## The declared outcome

An outcome lives in the held target's **output schema**, on the flow's single
result surface. The schema wraps the value in the run's result envelope — a
`status` string and a `result` object keyed by the collector's id — with the
outcome field carrying an `enum` of its values:

```json theme={null}
{
  "type": "object",
  "properties": {
    "status": { "type": "string" },
    "result": {
      "type": "object",
      "properties": {
        "collect": {
          "type": "object",
          "properties": {
            "outcome": { "enum": ["answered", "expired"] }
          }
        }
      }
    }
  }
}
```

Here the collector's id is `collect` and the outcome field is `outcome`, with two
values. A flow that flags exactly one result surface can declare one outcome; a flow
that flags none, or more than one, declares none.

The `ask_node` result beside its `outcome` also declares `answer`, `reply_to` and `params`:
an `answered` outcome carries all three.

## The synthesized conditional

Wiring the outcome adds one `conditional` node. Its id is the wired node's id with
`__outcomes` appended, and it carries one branch per wired value. Each branch's key
is the conditional's id with `__<value>` appended, its condition reads the wired
node's result at the pinned path, and its `path` is the target node the value routes
to:

```json theme={null}
{
  "id": "gate__outcomes",
  "type": "conditional",
  "data": {
    "branches": {
      "gate__outcomes__answered": {
        "condition": {
          "content": ".upstream_outputs.gate.result.collect.outcome == \"answered\""
        },
        "path": "routed_answered"
      },
      "gate__outcomes__expired": {
        "condition": {
          "content": ".upstream_outputs.gate.result.collect.outcome == \"expired\""
        },
        "path": "routed_expired"
      }
    }
  },
  "ui": {
    "source": "studio:outcome-chips",
    "node": "gate",
    "collectorId": "collect",
    "outcomeField": "outcome"
  }
}
```

The wired node here is `gate`; the conditional is `gate__outcomes`, with a branch
for each wired value. The graph gains one edge from the wired node into the
conditional and one edge from the conditional to each branch target:

```json theme={null}
{
  "edges": [
    ["gate", "gate__outcomes"],
    ["gate__outcomes", "routed_answered"],
    ["gate__outcomes", "routed_expired"]
  ]
}
```

## The pinned condition path

Every branch condition reads the wired node's recorded result at one fixed shape:

```
.upstream_outputs.<node>.result.<collectorId>.<outcomeField> == "<value>"
```

`<node>` is the wired node's id, `<collectorId>` and `<outcomeField>` are the two
names from the declared outcome, and `<value>` is the wired value. A branch that
reads this exact path is a wired outcome; a branch that reads anything else is a
plain hand-authored decision on the same field, and stays one.

## The `ui` marker is optional

The `ui` marker names the wired node and its outcome so the editor folds the
conditional back into chips when it loads the flow. The engine ignores it: it reads
the wire form **structurally** — the conditional's id, its branch keys, and each
branch's condition path — and drops the marker when it builds the flow. A
hand-authored flow that follows the id, branch-key, and condition-path shape above
is read and routed identically **with or without** the marker. Add the marker only
if you want the editor to render the wiring as chips.

## Expiry follows the wiring

An [ask holder](/babelfish#expiry-in-a-flow) whose held target has an `expired`
outcome earns its expiry behaviour from the wiring, never from an authored value.
When the `expired` value is wired downstream — the conditional carries a
`<node>__outcomes__expired` branch — the ask is started with `on_expiry` set to
**resume**, so a lapsed deadline resumes the run down the `expired` branch. Leave
the `expired` value unwired and the ask keeps the door's **kill** default: a lapsed
deadline ends the held chain. The behaviour is a pure function of whether the
branch is present, so a hand-authored flow that wires the branch gets the resume
behaviour with nothing else to set.

## See also

* [Calling another flow: cancel, resume, start](/babelfish#calling-another-flow-cancel-resume-start) — the holder node the outcome sits on.
* [Expiry in a flow](/babelfish#expiry-in-a-flow) — what the derived `on_expiry` does at run time.
* [The flows editor](/babelfish/studio) — wiring an outcome as chips instead of by hand.


# Access control
Source: https://docs.tai42.ai/concepts/access-control

The jq-policy request-auth gate.

Access control is the request-auth gate in front of a server. It resolves an
inbound API key to an identity, loads that identity's policy, and decides whether
the request may reach its route. It is on by default; it reads live auth context
(identity, the policy-version cache-buster, and live counters) from Redis and its
durable policy bodies and route mappings from Postgres.

This page explains the model. To turn the gate on and write a first policy,
follow [Set up access control](/guides/access-control).

> [!NOTE]
>
> For local development against tools that need no auth, turn the gate off with
> `ACCESS_CONTROL_ENABLE=false` — the [quickstart](/getting-started/quickstart)
> does exactly this.

Every request the gate admits also writes one **audit line** to the server log:
the principal the gate resolved (`anonymous` when the request carried no identity
— a public route, or the gate turned off), the method, the route, the response
status, how long it took, and a timestamp. It is on by default and turns off with
`TAI_AUDIT_LOG_ENABLE=false`. The route is the only request text on the line, and it is
the path *template*: a path parameter is written as its `{name}`, so a door that
carries its credential in the path (a trigger link's `/trigger/{token}`) records the
shape and never the secret. A stray path matches too on a deployment that serves the
Studio, where the SPA catch-all takes it: the line reads `/{spa_path}`, again never
the tail. A path nothing matched at all has no template to record, so the line reads
`<unmatched>` and carries no part of that path — as does a path handed on to a
mounted sub-server (`/app/{slug}`), which records the mount's own prefix and then
that same constant, `/app/<unmatched>`, because what the sub-server made of the rest
is not visible from here. Nothing else reaches the
line — never a request or response body, a query string, a header, or a token — so
the trail is safe to ship wherever your logs already go.

A refusal is on the same trail, so failed access is visible, not just granted
access. A request the gate turns away writes its own line: a `401` when it carried
no usable identity, a `403` when a known identity is not permitted, or a `429` when
the flood limiter sheds it. A denial line adds a `reason=` naming the cause it can
state (a permission miss, an unconfigured route), and its principal is the real
caller when the request was authenticated-but-denied, otherwise the marker
`unauthenticated`. A refusal records the same path *template* (or `<unmatched>`), so
it never leaks a path-borne secret either.

## Identity, policy, route

The gate has three moving parts, resolved on every request:

1. **Identity** — an inbound key is hashed and looked up; a stored key resolves to
   a `user_id`. A raw key is generated with a CSPRNG, only its SHA-256 is ever
   stored, and the plaintext is returned to the caller exactly once.
2. **Policy** — the identity's policy carries its scopes plus an optional jq
   condition and policy data. The policy is cached per worker and keyed on a
   version, so a management edit bumps the version and the next read bypasses the
   stale cache without waiting out the TTL.
3. **Route** — a request path maps to a scope id; the guard admits the request
   only if the identity's scopes cover it. A route pinned to the public marker
   (via `tai scopes public-pin`) is public; `*` is a superuser scope on a key, and
   it is also what a **registered, authenticated route with no mapping** resolves
   to — so every role-holder (which carries `*`) reaches such a route out of the
   box, while a scoped key needs an explicit row. Only a path the application does
   **not serve** fails closed for every ordinary identity — except a condition-free
   `*` super-admin key, which is admitted (a root can map the route anyway, so
   blocking it is a footgun, not security). So an access-control-enabled
   deployment's admin reaches the whole surface out of the box, every role-holder
   reaches every registered route, and the route table only ever adds scoping for
   scoped keys.

## Principals

Every credential resolves to a **principal** — the unit of identity the gate
loads a policy for. A principal is either a **human**, which signs in through an
[accounts](/concepts/accounts) provider, or a **service**, which never logs in
and holds keys only. Every API key belongs to exactly one principal — its
**owner**, recorded on the key at mint — and a key with no owner is a validation
error at mint and an invariant violation at read, never a silent default. The
deployment's first principal is the **owner**, created once through the
[setup door](/guides/access-control).

## Resolving a credential across providers

A deployment can enable more than one identity provider at once — an API-key
store, an [accounts](/concepts/accounts) provider's sessions, an issuer-JWT
verifier. `ACCESS_CONTROL_AUTH_PROVIDERS` is an **ordered** list, and the gate
resolves an inbound token by trying each provider **in order, first match
wins**: the first provider that recognises the token answers, and resolution
stops there.

The distinction that keeps this safe is **error is not miss**. A provider that
does not recognise a token returns "not mine" and the gate falls through to the
next provider. A provider that recognises the token but hits a backend failure
**raises** — it does not silently return "not mine", which would let a
misconfigured store fall through to a weaker provider. A miss falls through; an
error fails closed.

## Attenuation is enforced at the gate

When an [accounts](/concepts/accounts) provider is in play, a resolved API key
carries its owning account, and the gate applies **owner attenuation** on every
request: the key's effective authority is intersected with its owner's live
policy right here, at resolution time, before the policy decision. Because it is
re-applied per request rather than frozen at mint, a change to the owner's role —
or disabling the owner — takes effect on the key's very next call. Only the mint
path may set the owner claim; the gate strips any owner claim a non-minting
provider returns, so an external issuer can never assert ownership it did not
earn.

The owner every door reads is the one recorded on the key's **stored policy** at
mint. Where a credential is verified, the owner it carries must equal that stored
owner: a credential whose owner claim differs is denied (a `403` at the request
gate; a `400` where a key is named as input, as at claim-link creation) and the
mismatch is logged as an error, never resolved silently in favour of either copy.

> [!NOTE]
>
> A key that carries an owner claim is an **owned key** — a capped, isolated
> sub-identity you can hand to a teammate, a device, or a machine. The delegation
> model, the `GET /api/auth/me` capability projection, per-identity data isolation,
> the claim-link channels, and which scopes are safe to grant live on
> [Owned keys](/concepts/owned-keys).

## The login routes are public; `/api/auth` stays reserved

Human [login](/studio/login) flows live under the `/api/login` namespace — the
methods listing, the credential-submit routes, the setup door and invite flows.
Each login route is **public by its own declaration**: a browser must reach it
*before* it has any credential, so the route says so where it is registered, not in
a route mapping an operator has to remember to add. The `/api/auth` provisioning and
policy routes stay **reserved** behind the gate — minting keys, editing policies,
and managing principals all require an authenticated, authorized caller. Sign-in is
open; administration is not.

## Routes declare their reach

Beside its public-ness, a route declares the reach the gate gives it, with three
flags on its registration (`custom_route`, or the plugin route module's own call):

* **`pre_auth`** — a pre-authentication route (login, recovery, claim exchange). A
  credential presented on it is **never verified**, so a stale session or key the
  browser still sends cannot lock a caller out of the door that replaces it; the route
  is public and no policy layer runs, at the HTTP edge and when it is reached as a
  tool alike. Only a public route may declare it. Every login route the platform and
  its accounts plugins ship declares it. Any other public route still verifies a
  presented credential, so it keeps the caller's identity when one is sent.
* **`any_authenticated`** — reachable by **any** authenticated identity, whatever
  its scopes and whatever the route table maps: `GET /api/auth/me` (the
  [capability projection](/concepts/owned-keys)) declares it, so a scoped key that
  holds no `"*"` can still introspect. The base-tier role condition still applies,
  and an unauthenticated caller is refused `401`. The reach is the same at the HTTP
  edge and when the route is reached as a tool — over MCP or by a background run: the
  scope test is skipped, and the jq conditions and the per-tag access-level pass still
  run. Only an authenticated route may declare it.
* **`self_service`** — a caller self-service surface under the reserved `/api/auth`
  area: own keys, the tokens payload, claim-link creation, the read-only scopes
  listing, logout, and a provider's own-credential routes. The seeded `editor` and
  `viewer` role conditions are **built from these declarations** on the methods each
  route serves, so a plugin that ships such a route is carved in without the platform
  naming it. A `viewer` reaches only the state-changing ones among them; an
  admin-only action class (the policy history and rollback) still fences a route
  whatever it declares.

A flag that contradicts the route's public-ness — `pre_auth` on an authenticated
route, `any_authenticated` on a public one — is a registration error. The boot also
refuses a registry holding an authenticated route that declares `pre_auth`, the flag
that skips credential verification. None of these is a setting: an operator's own
always-public prefixes (`ACCESS_CONTROL_ALWAYS_PUBLIC_PATH_PREFIXES`) still feed the
same credential skip, for a login page the deployment serves outside the registered
routes, and default to none.

## The Studio SPA shell is public; its data is not

An unmatched non-`/api` GET is served the **dataless Studio SPA shell** —
`index.html` and its static assets — so a refresh or bookmark of an inner Studio
route (`/agents`, `/settings`) lands the app, not a `404`. This is on by default
(the `spa_shell_public` setting) and safe: the shell carries no data — everything
it renders sits behind an authenticated `/api/*` call — so an unauthenticated
visitor sees only the login page. Deep links therefore work with **no manual
public pin** for `/` or any SPA path. Because the guard resolves deny-wins, an
over-broad protected mapping that also covers SPA paths suppresses this fallback, so
the refresh meets a `401` rather than the shell — scope a protected pattern to a real
surface, never the whole site. The fallback is GET-only and never touches the
**control plane** — `/api` plus the path the streamable-http MCP transport is mounted
at (`/mcp` by default, the configured path otherwise; an SSE-only deployment has
`/api` alone) — so it can never open it; a headless deployment
turns it off by setting `spa_shell_public` to `false`. See
[deploying the Studio](/operate/studio#deep-links-under-access-control).

## Routes declare their own public-ness

A route declares whether it answers unauthenticated at registration — a core
native route registered `authed=False` (the interactions callback and served-media
capability doors), or a plugin route carrying its own `public` flag in the plugin's
[descriptor](/concepts/marketplace#declared-http-routes). The route registry records
that declaration against the route's single owner, and the gate reads it as a tier of
its own: after the always-public prefixes and patterns resolve, and **before** the
Postgres route-table lookup, the gate matches the request `(path, method)` against
the registry — a match on a route declared public is served unauthenticated,
whatever its owner. So a core capability door or a plugin's inbound webhook is open
the moment it registers, with **no** route row to add and no pin to remember.

The tier is **per-method**. It resolves only the exact methods a route declares
public: a `POST` declared public opens, while a `GET` on the same path that is not
declared public falls straight through to the normal gate. And because every route
has [one owner](/concepts/marketplace#declared-http-routes) — two owners can never
both claim one path shape and method — the declaration is the whole source of truth.
Nothing is ever written to the `access_control_routes` store for a declared-public
route, so there is no stored row to drift out of step with the code.

The declaration is **authoritative**: because the tier short-circuits above the
route-table lookup, an operator cannot re-protect a declared-public route in place
with a later route-table pin — the pin never gets consulted. A core capability
door's declaration is fixed in the platform code; to close a plugin door, decline it
at the install-time public-acceptance gate or uninstall the plugin. Remapping only
relocates the public route, it does not protect it. The operator's own hand-pin door
stays for the operator's own routes.

A scope mapping would read as protecting such a route while it stays open, so the
scope writer refuses one: mapping a URL into a scope (`POST /api/auth/scopes` over
HTTP or as a tool, `tai scopes add`) is refused with a `400`, nothing written, when a route
declared public serves that URL on any method, and an `access_control` restore names
such a mapping in its section's errors and restores the rest. The routes listing
(`GET /api/auth/routes`, `tai scopes routes`) marks each route public by its own
declaration with `declared_public: true`, read through the same predicate as this
tier.

The reserved namespace still wins. A declared public route resolving under a
reserved prefix — `/api/auth` by default — is refused at boot, not quietly opened,
so no owner can declare its way past the reserved control plane described above. The
operator's own public-pin door (`tai scopes public-pin`) is unchanged and
independent — it maps a route row public in the store, which is a separate tier from
a route's own declaration.

## Flood control on public doors

Every public door is rate-limited, and the coverage is **derived, never listed**: a
route declares whether it is public, the route registry records that, and the limiter
throttles every route registered public. A new public door — a plugin's inbound
webhook, another login door — is flood-limited the moment it registers. Authed routes
pass straight through; the credential is the gate there.

A request is answered by the most specific registered route that covers it, so a
concrete door always outranks the SPA catch-all, and a path no registered route
matches is not the limiter's business.

### Door families

Public doors are grouped into **families** whose counters are disjoint, so a flood on
one door can never exhaust another's budget. A family is the door's path stem — its
leading static segments, at most two, stopping at the first `{parameter}`, with the
shared `/api` segment dropped:

| Door | Family |
| - | - |
| `GET\|POST /trigger/{token}` | `trigger` |
| `GET\|POST /universal_webhook/{topic}` | `universal_webhook` |
| `GET\|POST /api/interactions/callback/{ticket}` | `interactions_callback` |
| `GET /health`, `GET /ready` | `health`, `ready` |
| `POST /api/channels/slack/inbound` | `channels_slack` — one family per channel |

Two segments is what keeps a deployment's families disjoint without splitting one
door's own surface, while every channel keeps a family of its own. A path
parameterised from its first segment — the SPA catch-all `/{spa_path}` — has no stem
and folds into `root`.

A route may name its family instead (`DeclaredRouteMetadata.rate_limit_family`): the
web chat's doors declare `channels_web` and its upload door `channels_web_uploads`, so
their families hold whatever mount base the plugin is installed under.

### Budgets

A route declares its family's default budget
(`DeclaredRouteMetadata.rate_limit_budget`, a `RateLimitBudget(limit=…, burst=…)`), and
every public route of one family declares the same one: a family whose routes disagree —
or where one route declares and another forgets — fails the boot, or the reload that
installs it, before it serves. A family whose routes declare nothing is charged
**600 requests a minute** with a **120-request burst in any 10 seconds**.

The runtime's three single-request doors — `trigger`, `universal_webhook`, and
`interactions_callback` — declare 60 a minute and 10 in 10 seconds, because one request
there buys real work: a webhook fan-out, a ticket redemption, a tool run. The web chat
declares `channels_web` at 120 a minute and 30 in 10 seconds, wide enough for one first
page load (the chat page plus every bundle file it links in a single burst), and
`channels_web_uploads` at 20 and 5.

Over either window the door answers `429` with a `Retry-After` naming the seconds
left in that window, and the refusal writes its own audit line as an unauthenticated
request against the route template.

### Tuning a family

`TAI_RATE_LIMIT_FAMILIES` overrides one family's budget, as a JSON object or per
field:

```bash theme={null}
TAI_RATE_LIMIT_FAMILIES='{"trigger": {"limit": 240, "burst": 40}}'
TAI_RATE_LIMIT_FAMILIES__TRIGGER__LIMIT=240
```

Each field resolves on its own, most specific first: the operator's override, then
the budget the family's routes declare, then the default — so an override naming only a
limit keeps the declared burst. `TAI_RATE_LIMIT_DEFAULT_LIMIT`,
`TAI_RATE_LIMIT_DEFAULT_BURST`, and `TAI_RATE_LIMIT_DEFAULT_ENABLED` move the default
every family whose routes declare nothing starts from. Switching a family off is the
operator's alone: a route declares a budget, never an off switch.

An override **tunes or disables** the door it names; it never widens coverage.
`{"enabled": false}` passes that family through, and an entry for a family no route
declares is inert.

### Which client a request is from

The counter is keyed per client address, and `X-Forwarded-For` is caller-writable
text — any client can claim any address in it — so it is believed only under a
declared trust statement:

* **`TAI_RATE_LIMIT_TRUSTED_PROXIES`** — the addresses your proxies call from, single
  hosts or **CIDR blocks**. The socket peer must itself be trusted before a header
  byte is read; then the right-most entry that is not itself a trusted proxy is the
  client.
* **`TAI_RATE_LIMIT_TRUSTED_HOPS`** — the number of proxies sitting in front of the
  deployment. Use it when the proxy's own address moves (a managed load balancer
  renumbers): the limiter skips exactly that many right-most hops instead of matching
  addresses. A positive value **wins**, and the roster is then not consulted.

Anything else fails closed to the socket address — an untrusted peer, a chain too
short for the declared hop count, an entry naming no address — and the fallback is
reported in the log, never silent. An IPv6 client buckets by its `/64`, since one
host routinely holds a whole `/64`.

The same resolution keys the setup door's wrong-token throttle and an accounts
provider's login throttles, so one trust statement holds for every door that counts
per client.

With neither setting, `X-Forwarded-For` is ignored and the socket peer is the client:
correct for a directly exposed deployment, and behind a proxy it collapses every
client into one bucket. Boot emits a `WARNING` when no trust is declared, and a
forwarded header arriving under that posture is reported once more.

### No Redis, no limiter

The counters live in Redis — `TAI_RATE_LIMIT_REDIS_URL`, or the shared
`TAI_DEFAULT_REDIS_URL`. With neither, rate limiting is **OFF**: every public door
passes through unthrottled and boot emits one `WARNING` naming the variable, never a
boot refusal. See [what OFF looks
like](/concepts/config-and-secrets#what-off-looks-like) and the
[`RateLimitSettings` table](/reference/settings#ratelimitsettings).

> [!WARNING]
>
> **Application abuse, not volumetric attack.** This limiter counts requests per client
> per family *after* they reach the app, which is what bounds scanning, credential
> stuffing, and a hot webhook. It is not a DDoS defence: a flood large enough to
> saturate your bandwidth, connection table, or worker pool has to be absorbed before
> the app sees it — by a CDN, an edge WAF, or your ingress. Self-hosted deployments put
> one in front of the runtime; the split between edge volumetrics and in-app abuse
> limits is the standard one.

## Admin-only mutations

Beyond the editable per-tag role map, some routes are **never grantable** — no
per-tag level opens them for any non-admin. The fence is **declared on the route**,
not maintained as a hand-written list: every authed route declares an
action-class, and two of the classes are the admin-only fence:

* **`fenced`** — the admin-only mutations: the pre-existing infrastructure
  changes and the role and policy control plane. Running a tool **directly**
  (`POST /api/run-tool`); reloading or removing a tool; the `config` env write and
  reload (`POST /api/config/env`, `/api/config/reload`); replacing the manifest;
  reloading failed MCPs and deregistering an MCP; reloading the fleet; marketplace
  install / uninstall / update; backup import / export; and the role and policy
  control plane (creating, editing, deleting, and rolling back roles, and rolling
  back a user's policy). Editing scopes, the route table, and the public-route
  pins is **not** `fenced` — those routes are ordinary `read`/`write` class, made
  admin-only by the base-tier `/api/auth` control-plane ceiling that default-denies
  the area to every non-admin role.
* **`secret`** — the admin-only reads, over two admin-owned stores. The bulk
  role / policy reads: the roles listing (`GET /api/auth/roles`), the role version
  histories, and a user's policy version history, whose payload carries raw jq
  policy bodies. And the deployment config store: the stored environment
  (`GET /api/config/env`) and the per-settings-class values
  (`GET /api/config/settings-schema`). Environment and settings are one
  admin-owned store — including deployment secrets such as the connector encryption
  key — so only an admin reads or writes it.

An `admin` reaches all of them; an `editor` or `viewer` is denied. Everyday
**feature** configuration is **not** on this fence: starting an async tool-run
(`POST /api/tool-runs`), scheduling a tool, setting the MCP config, reloading a
single MCP server, mounting a sub-MCP, setting tool extensions, registering hooks,
and reading the hooks listing are ordinary grantable `read`/`write` routes an
editor reaches — an editor configures every feature through the feature's own
routes. The deployment env/settings store is the admin-owned exception. A route
that declares no action-class fails boot, so the fence can never be silently
forgotten. See
[user types and permissions](/concepts/permissions) for the full surface and the
per-tag [role model](/concepts/accounts#roles).

> [!NOTE]
>
> **Editors configure every feature; they do not own the deployment store.** An
> `editor` reaches the async tool-run surface, schedules, the MCP config, sub-MCP
> mounts, tool extensions, and hooks through each feature's own grantable routes —
> the platform trusts a granted role to operate the features it holds. The
> deployment env/settings store stays admin-only: reading the env and settings
> (`GET /api/config/env`, `GET /api/config/settings-schema`) and the env write are
> admin-only, alongside the infrastructure mutations and access-control
> administration above.

## The jq policy

A policy is scopes plus rules. The rule is a **jq condition** evaluated against the
request's credentials and context — expressive enough to gate on identity, scope,
and request attributes without any custom code. The condition is compiled and
evaluated by the policy enforcer; a backend error while reading the policy version
**fails closed** by raising, which surfaces as a clean deny rather than a silent
default.

The condition reads the request as `.request.method` and `.request.path`. The path is
the **canonical** request path, the same on every door that evaluates a condition (the
HTTP gate, a tool call, a background fire): any mount prefix the app is served under
(its ASGI `root_path`) is removed, each segment is percent-decoded once, repeated
slashes are collapsed, `.` and `..` segments are resolved, and a trailing slash is
dropped. A condition written as `.request.path | startswith("/api/auth")` therefore
holds on a deployment mounted at `/mnt` exactly as at the root, and `/api/auth/me/`
reads as `/api/auth/me`.

A denied request never leaks internal detail: an authentication failure returns a
fixed `401` and an authenticated-but-forbidden request a fixed `403`, with the full
failure logged only server-side.

Validate a jq condition offline before you commit it, and mint keys with the CLI:

```bash theme={null}
tai keys validate-condition --condition '.method == "GET"'
tai keys create --user alice --description 'CI key' --scope read --condition '.method == "GET"'
```

## Route mapping is two-tier

Mapping a route to a **named scope** (or pinning it public) is a configuration
decision, not a property of the route code. It is two-tier: a path pattern maps a
URL to a template key, and a Postgres record in the access-control policy store
maps that template key to a scope id (or the public marker). A route's own
*protection* — authenticated-or-public, and its action class — is declared in the
route code; the route table does not decide whether `/api` is private, it **refines
scope for scoped keys**. A registered authenticated route with no row is reachable
by every role-holder (it resolves to the universal scope); a row narrows it so a
key holding only named scopes can reach it too.

The **MCP transports and the sub-MCP mount** are authenticated surfaces the same
way: a role-holder reaches them out of the box, and a scoped key reaches them where
the operator maps them. This is how the [interactions](/concepts/interactions)
callback doors are declared public while the stream and answer doors stay
protected.

Every management mutation that touches more than one key commits through a single
WATCH/MULTI/EXEC transaction, so a crash never leaves the store half-written and a
concurrent edit aborts and retries against fresh state.

See the [access-control guide](/guides/access-control) for the provisioning
workflow, the [CLI reference](/reference/cli/index) for `tai keys` and
`tai scopes`, and the [HTTP API reference](/reference/api/index) for the routes.


# Accounts
Source: https://docs.tai42.ai/concepts/accounts

Human accounts, sessions, and the login flows that sign a person in.

Accounts are the human side of [access control](/concepts/access-control). An
accounts provider owns user records and the login flows that sign a person in —
password forms, invites, first-run owner creation, and browser sign-in — and
mints the session tokens those flows return. It is an opt-in plugin kind: a
server with no accounts provider still authenticates API keys, it just has no
human login.

## Accounts and identity are two kinds, one seam

The platform keeps two auth-related plugin kinds with one purpose each:

* An **[identity](/concepts/access-control) provider** answers a single
  question — *who is this token?* — for whatever credential arrives: an API key,
  an issuer-minted JWT, or a session token. It validates and returns an
  identity; it mints nothing on a human's behalf.
* An **accounts provider** owns human accounts and the login flows that *create*
  sessions for them. Crucially, an accounts provider **is** an identity
  provider: the session tokens it mints are validated back through the same
  `validate_token` seam every other credential passes through. Installing an
  accounts provider never adds a second enforcement pathway — the request gate
  stays the one gate.

Splitting the kinds this way keeps each provider single-purpose: a pure identity
provider (an API-key store, an issuer verifier) never grows login UI, and an
accounts provider never becomes a parallel authorization path.

## The session model

A login flow returns an **opaque session token** — a random string the server
mints, with no parseable contents. The recommended prefix is `tai-sess-`, so a
session token is distinguishable at a glance from an `sk-` API key, but the gate
never parses either; it hands the whole token to a provider to resolve.

Sessions are provider-owned and follow the same one-way-hashing discipline as
API keys: only a hash of the token is stored, the plaintext is returned to the
browser once, and a session carries a TTL so it expires without an explicit
logout. Logout revokes the session server-side; a revoked or expired token
resolves to no identity and the request is denied like any other bad credential.

## Keys are owned credentials

With accounts in play, an API key is no longer a free-standing secret — it is a
credential **owned** by an account. The mint path records the owning account on
the key, and the request gate enforces that ownership on every call:

* A key can never out-scope its owner. A key minted by a non-admin is
  **attenuated** to a subset of the owner's own authority; a mint that asks for
  more than the owner holds is rejected at mint time.
* The owner's authority is enforced *through* the key on every request, not just
  captured once at mint. This is what makes attenuation hold **over time**: when
  an admin changes an owner's role, or disables the owner, the owner's live
  policy changes and every key that owner holds is re-evaluated against the new
  policy on its next request. A key does not carry a frozen snapshot of what its
  owner could once do.

For automation, an admin creates a **service principal** — a non-human identity
that holds keys but never logs in — and mints keys owned by it. That keeps the
machine-to-machine path alive while making the common case (a key tied to a
person) the default. See [API keys](/studio/api-keys) for provisioning and the
ownership cap.

## Roles

An account's authority comes from a **role** — a named, editable permission set
an admin assigns by name. An account's enforced policy carries a **live pointer**
to its role, not a copy: enforcement reads the role's current definition on every
request, so an edit to a role changes every holder's access on their next request,
and moving an account to a different role re-points it immediately.

A role's editable part is a **per-tag access-level map** — each feature group is
set to `none`, `read`, or `write` — composed with a non-editable base-tier ceiling
and the admin-only route fence (see
[user types and permissions](/concepts/permissions)). The platform seeds three
roles: **admin** (full control, reserved and permanent), **editor** (`write` on
every grantable feature group), and **viewer** (`read` on every grantable feature
group). An admin can also **create, edit, delete, and roll back** custom roles —
through the Studio or the [`tai roles`](/reference/cli/roles) CLI. Because the role
sets the owner's live authority, moving an owner from editor to viewer, or editing
either role, immediately re-attenuates every key that owner holds, without touching
the keys themselves.

## First run and invites

A fresh deployment has no principal. The login surface reports this as
`needs_setup`, and the one-step [setup door](/guides/access-control) initializes
the deployment exactly once: it creates the **owner** principal — the initial
admin — and mints the owner's first key, and when an accounts provider that
attaches an interactive login is configured it also sets the owner's password
(or issues an invite to set one later). The door closes the moment the owner
exists — a second call is refused — and concurrent first-run attempts are
resolved so exactly one owner is ever created.

After that, an admin grows the user set by **invite**: the admin creates an
account — a human principal — and issues an invite, and the invited person
follows an invite link to set their own password and activate the account.
Invites are single-use and time-bounded — an expired or already-accepted invite
is refused.

## What the Members page governs

The Studio's Members page manages **only human accounts** — the `usr-*`
principals an accounts provider owns. It reads the deployment's
[member actions](/concepts/member-actions): a provider declares what can be done
to a member — invite a user, send a new login link, cancel an invitation, change
a role or access, remove one of a member's logins, remove a member — and the page renders those declarations as
page buttons and per-row menu items, performing one through a single invoke door.
The role picker reflects the **current editable role set** — the seeded
admin/editor/viewer plus any role an admin has created — so a newly authored role
is assignable the moment it exists. A member's role is the one every login of
theirs holds; a member whose access was set directly rather than from a role shows
**No role**, and a member whose logins hold different roles shows **Mixed roles**
with each login's own role. A provider's change-role action gives every login of the member one role, which clears it. Removing, disabling, or demoting the last enabled admin is refused —
see [the last enabled admin stays](/concepts/permissions#the-last-enabled-admin-stays). It deliberately does **not** list non-human
principals, because they are not accounts:

* `sk-*` — machine API keys — are governed on the
  [API keys](/studio/api-keys) surface.
* A principal provisioned directly through the
  [access-control](/concepts/access-control) policy routes is governed there.

So an operation that looks like "disable this admin" is a *different* action
depending on the principal type: disabling a human account is a Members-page
action, while disabling a policy-provisioned admin is a policy-route action
against that principal. One principal type, one governing surface.

## See also

* [Access control](/concepts/access-control) — the request-auth gate accounts
  plug into, and multi-provider resolution.
* [Member actions](/concepts/member-actions) — the provider-declared member-admin
  actions the Members page renders and invokes.
* [Sign in to the Studio](/studio/login) — the login surface these flows render.
* [API keys](/studio/api-keys) — owned keys and the attenuation cap.


# Agents
Source: https://docs.tai42.ai/concepts/agents

LLM-driven capabilities and how they are authored.

An agent is an LLM-driven capability registered alongside tools. You author it
against one uniform contract — the `Agent` ABC — and the [manifest](/concepts/manifest)
loads it the same way it loads a tool module.

## The Agent contract

The whole agent shape is owned once by the contract: the `Agent` ABC with its
default stream and drain behaviour, the neutral spec descriptors, and a typed
event vocabulary. The skeleton adds no agent implementation of its own — it
surfaces the contract in its own namespace and registers agents against the app.

You register an agent with a decorator that also names it. The skeleton
synthesizes the agent's JSON `run` tool from its declared input model, so an agent
is callable exactly like any other tool:

```python theme={null}
from pydantic import BaseModel
from tai42_contract.agent import Agent
from tai42_contract.app import tai42_app


class GreetInput(BaseModel):
    text: str
    times: int = 1


@tai42_app.agents.agent("echo_agent")
class EchoAgent(Agent):
    tool_name = "echo_agent"
    tool_description = "Echo text a number of times."
    ToolInput = GreetInput

    async def run(self, *, text: str = "", times: int = 1, **_):
        return text * times
```

An agent whose run can park (it async-asks, or its tool calls park it) declares that its
run tool can pause, `meta={"tai42/pauses": True}` on the decorator, like any
[tool that can pause](/guides/build-a-tool#tools-that-can-pause). A tool an agent calls
that parks without that declaration fails the agent's run with `UndeclaredPauseError`
naming the tool; the model is never handed a tool error to retry around, so the tool's
body runs once.

An `ask` inside an agent's run returns `{answer, reply_to, params}`, as it does anywhere
(see [Block or park](/guides/use-interactions#block-or-park-sync-and-async)). A parked
agent run resumes through the agents' continuation tool (`agent_resume`), which is run
with `answer`, `reply_to` and `params` and hands the waiting `ask` the same object.

## Streaming events

An agent run streams a typed sequence of `StreamEvent`s rather than returning a
single blob. The vocabulary covers message deltas and finals, reasoning steps,
tool-call and tool-result steps, structured finals, interrupt finals, and run
usage. The event producers — the projection over the agent runtime's updates and
messages — live in the agents runtime; a client renders the frames as they arrive.

When a run carries a `response_format`, the structured result reaches a
user-visible stream **only** as the terminal structured final — the stream carries
no synthetic structured-output tool-call/result frame for the internal call that
produced it.

A structured-output run that never conforms, or one that exhausts its graph step
limit, ends with a typed non-fatal terminal — `structured_output_unresolved_final`
(the schema, the attempts, the last validation error) or `recursion_limit_final`
(the limit) — that a flow or route branches on by `type` rather than receiving a
generic failure. The re-prompt bound is the server-wide
`TAI_AGENTS_STRUCTURED_OUTPUT_REPROMPT_CAP` (default 3).

Run an agent and watch its stream from the CLI:

```bash theme={null}
tai agents run <name> --input '{"text": "hi", "times": 2}'
```

## Context management

Before each model call an agent trims its conversation history to fit a token
budget — the default context-management strategy, configurable via
`CONTEXT_OVERFLOW_METHODS` — keeping the most recent turns and dropping older
ones; a trim that drops history logs a warning. The newest human message is never discarded: when the
budget cannot hold the system prompt plus the current message, the run raises a
typed `TrimmingBudgetTooSmallError` naming the budget rather than answering from
the system prompt alone, so an overflow surfaces loudly instead of returning a
silently wrong reply. Raise the budget with `TRIMMING_MIDDLEWARE_MAX_TOKENS`.

The system prompt is **per-run configuration**, supplied fresh at each model call
(`create_agent(system_prompt=...)`) — it is never stored in thread or checkpoint
state. Any system message found in replayed thread history is stripped before the
model sees it, so the prompt comes only from the run's own configuration; it counts
against the trimming budget above.

## System-prompt caching

Every agent turn re-sends its whole system prompt. On a provider that takes a
system-prompt cache breakpoint, marking that stable prefix lets the provider cache
it and read it back on later turns instead of re-billing it. This marking is **on
by default** (`TAI_AGENTS_SYSTEM_PROMPT_CACHE_DEFAULT=true`), server-wide; a provider
that caches without a mark, or supports none, is left unmarked.

A `tools_agent` node overrides the default with `system_content_kwargs`: leave it
unset to take the default, pass `{}` to opt the node out (no mark), or pass an
explicit mark of your own. Most agent faces carry the default; the retrieval agent
and the Claude Code agent are excluded — see [the agents
plugin](/plugins/tai42/agents) for the per-face detail.

## Authored agents

Beyond code-defined agents, you can author an agent as a saved spec that rides the
[versioning spine](/concepts/versioning-spine) — a preset that bakes the agent's
preset-bakeable fields. Authored agents version and roll back exactly like
[presets](/concepts/presets), so an agent's configuration evolves without breaking
its callers.

## Composition

An agent can drive other agents as sub-agents and chain multi-step work. That
compositional side — sub-agents and the ready-made set — is its own pillar:
[deep agents](/concepts/deep-agents). The platform ships ready-made deep agents
that run that durable, code-executing work over the [sandbox](/concepts/sandbox) —
the execution surface an agent reaches for a persistent workspace and code — see
[the agents plugin](/plugins/tai42/agents) and
[the guide](/guides/use-the-ready-made-agents).

See the [author-an-agent guide](/guides/author-an-agent) for the full authoring
path and the [Python SDK reference](/reference/python-sdk/index) for the `Agent`
ABC and the `StreamEvent` types.


# Asking the caller
Source: https://docs.tai42.ai/concepts/asking-the-caller

A run that pauses to ask the run that called it, and the door contract that resolves it.

An [interaction](/concepts/interactions) normally asks a **person**. A **caller
ask** asks the **run that called this one** instead: the asking run pauses and hands
its question up, and the calling run answers by resuming it. Nothing reaches a human
inbox and nothing is delivered out of band — the question lives entirely between the
two runs.

A tool or agent raises one by passing `to="caller"` to [`ask`](/concepts/interactions):

```python theme={null}
answer = await ask(
    "proceed?",
    answer_format="confirm",
    to="caller",
    mode="async",
    expiry_at=deadline,
)
```

`to="caller"` is always `mode="async"` and requires an ambient state context — the
ask **parks** the asking run and returns a suspension sentinel at once. The answer is
handed back by whoever resolves the park, never by an answer door. A caller ask may
carry a structured **`payload`** the resolving run reads in place of (or beside) the
`question`; `payload` is forbidden on a `to="user"` ask.

## Parks on the subject

A caller ask parks on the asking run's **subject** — the same subject a
[state binding](/concepts/states#a-bindings-subject-and-scope) resolves. Every park on
that subject is one **parked entry**, and the run that owns the subject sees the whole
set. An entry carries its `id` and `status` and, while it is a live ask, its
addressing and question fields:

```json theme={null}
{
  "id": "i-42",
  "status": "asking",
  "to": "caller",
  "asked_by": ["main"],
  "question": "proceed?",
  "answer_format": "confirm",
  "group_id": "g-1"
}
```

A `status` is one of `asking` (a pending ask), `running` (an ask being resumed),
`finished` (a resolved run's waiting outcome holding a result), or `failed` (a
resolved run's waiting outcome that raised). An entry's unset optional fields are
**absent**, never present as null keys.

A tool run through the background **submit** door answers a park exactly as the
synchronous run-tool door does: its run record ends `status: parked` carrying the
`asks` entries above when the tool asked its caller — else the suspension sentinel
when only a `to="user"` ask is open — alongside the `resumed_interactions` it
resolved on the way.

## The door contract

A **door** that can drive a parkable run — a [conversation
route](/reference/conversation-bridge), a [hook](/concepts/hooks), or a
[schedule](/guides/schedule-a-tool) — carries up to four optional jq expressions, the
**door contract**. Each runs over the door's own input document with the run's parked
entries bound as the jq variable [`$parked`](/concepts/jq-variables), so an author
branches on what is already parked:

| Expression | Yields | Effect |
| - | - | - |
| `cancel_expr` | `null`, an id, or a list of ids | Cancel each named park (a whole-chain kill); the delivering channel releases its hold and nothing is delivered to the person. |
| `resume_expr` | `null`, `{id, payload}`, a bare id, or a list of these | Resume an ask with an answer (`{id, payload}`), or **take** a waiting outcome (a bare id). |
| `start_expr` | an object, or `null` | The kwargs the started target runs on; `null` starts nothing. No `start_expr` starts the door's own default kwargs. (A flows-engine [holder](/babelfish#calling-another-flow-cancel-resume-start) instead merges its `start_expr` result over the resolved node input, the expression's keys winning.) |
| `extras_expr` | an object, or `null` | The [`extras`](#extras) mapping handed to the started target. |

Each expression yields **one** value; a program that emits more than one, or a result
outside the shape its column names, is a loud error, never a silent default. An
undeclared `$name` is refused at save.

```jq theme={null}
# cancel_expr — cancel every parked interaction:
[$parked[].id]

# resume_expr — answer the first pending confirm ask:
{id: $parked[0].id, payload: {answer: "yes"}}

# start_expr — pass the count of what is already parked to the started run:
{payload: .msg, waiting: ($parked | length)}
```

At most **one** non-cancel action runs per visit: a door resumes, or takes, or starts
— cancels always run first. The order is fixed for every door.

A door may pass the visit an `on_act` notice to learn where the visit crosses from
checking to acting. The visit awaits it with `phase="before"` before the cancels,
before each resume or take claim and before the start, and with `phase="committed"`
after each claim commits — never during the checks. A raise from a `before` notice
leaves that action undone. A door that recorded a `before` claim notice and never saw
its `committed` notice can call `tai42_app.interactions.settle_visit_claim`, which
returns the ids no longer open. An empty result proves the claim did not commit; a
returned id was resolved by some door, and the read does not say which, so the door
must not treat it as its own commit.

## Resume, take, and cancel

* **Resume** an `asking` caller ask by naming its `id` with a `payload`: the payload
  is the answer, the parked run resumes under its own identity, and its next outcome —
  a result, fresh caller asks, or a re-park — comes back. A resume is an answer that
  came over no channel, so the resumed `ask` reads the payload as `answer` with
  `reply_to` and `params` `null`.
* **Take** a `finished` waiting outcome by naming its bare `id`: the resolved run's
  result is returned. Taking a `failed` outcome **raises**, so the taker fails as the
  resolved run did.
* **Cancel** any parked interaction by naming its `id`: it and every run linked above
  it are torn down for good. The channel that delivered the ask releases what it held for
  it, and a run a door started with a receiver is delivered `withdrawn`, so nothing is said
  to the person (see [Withdrawing a parked ask](/concepts/interactions#withdrawing-a-parked-ask)).

## Waiting outcomes

When a resumed run finishes but the run that resumed it cannot take the result inline —
a [hook](/concepts/hooks) or a [schedule](/guides/schedule-a-tool) fire has no
receiver — the terminal **waits** on the subject as a `finished` (or `failed`) parked
entry. The subject's next owner **takes** it. A waiting outcome never taken is dropped
past a retention horizon and the drop is surfaced as a platform event, never lost
silently.

## Extras

`extras_expr` builds an **extras** mapping handed to the started target beside its
kwargs. A target declares the extras keys it reads at registration; the visit refuses
an **undeclared** key before the run starts, so an extras injection never reaches a
target that never asked for it. `extras` ride only a **start** — never a resume, take,
or cancel.

## The generic tools

A run inspects and resolves the parks on its own subject with three builtin tools —
the LLM-facing face of the same door contract:

| Tool | What it does |
| - | - |
| `list_parked()` | Return every parked interaction on the run's subject — the full entries above. |
| `resume_parked(interaction_id, payload=…)` | With `payload`, resume that ask with the answer; with `payload` omitted, **take** the named waiting outcome. |
| `cancel_parked(ids)` | Whole-chain kill each named interaction; nothing is delivered to the person. |

They read and write the same subject a door contract does, so an agent resolves a
caller ask by hand exactly as a route resolves one by jq.

## Hidden from the inbox

A caller ask is **not** a human question. Every user-facing read surface hides it and
every user-facing resolution door refuses it: it never appears in the [interactions
inbox](/concepts/interactions#the-doors) or its stream, and the human answer door
rejects it — a caller ask is resolved only by its calling run resuming, never by a
person.

## The concurrency cap

Caller asks — and the waiting outcomes they leave behind — are bounded by their **own**
ceiling, `INTERACTIONS_MAX_CONCURRENT_CALLER` (default `10000`), independent of
`INTERACTIONS_MAX_CONCURRENT`, which bounds `to="user"` asks. A caller ask at the cap
is refused loudly, exactly as a user ask is at its cap; a finished run's waiting
outcome is counted here but **never** refused, so a result is never lost.

## Expiry

A caller ask carries a deadline like any async park, and its `on_expiry` decides what
a lapsed deadline does: **`kill`** (the default) tears the whole run chain down, while
**`resume`** resumes the parked run with the reserved expiry marker so it takes its
expiry branch. See [async parks](/concepts/interactions#sync-and-async).

## See also

* [Interactions](/concepts/interactions) — the human ask this parallels.
* [jq variables](/concepts/jq-variables) — `$parked` and every other variable a door jq binds.
* [Conversation bridge](/reference/conversation-bridge) — a route as a parkable door.
* [Hooks](/concepts/hooks) and [scheduling a tool](/guides/schedule-a-tool) — the other parkable doors.


# Backends
Source: https://docs.tai42.ai/concepts/backends

Where tools run: background, scheduled, distributed.

A backend is where a tool actually runs when it should not run inline in the
request. It is the execution engine behind background, scheduled, and distributed
tool runs — and it is swappable, so the same tool runs the same way whichever
engine you choose.

## The backend seam

The `Backend` ABC is the contract; the skeleton re-exports it as the registration
seam and ships the callback glue that chains a backend result back into the
runtime. Concrete worker backends — for example ones built on Celery, RQ, or arq —
are external [plugins](/concepts/config-and-secrets) that implement the ABC and
register through `tai42_app.backends.register_backend` when the
[manifest](/concepts/manifest) names the `backend_module`.

When a backend chains a follow-up step after a tool result, a failure in that
follow-up delivery is surfaced through the backend's own failed-job machinery —
recorded and retried under the backend's policy — rather than being discarded. A
lost follow-up is therefore visible in the backend's failed-job view, not silent.

The backend runs as its own process:

```bash theme={null}
tai backend
```

A registered backend adds a separate task runtime, so the deployment is now a
fleet of more than one process. Keeping those processes converged on a config
change is **not** the backend's job — it is the app's own
[worker bus](/concepts/worker-bus). Because a backend makes the deployment
multi-process, naming a `backend_module` requires the bus: set `TAI_BUS_REDIS_URL`
or the server refuses to start.

It also requires a shared [hooks registry](/concepts/hooks#managing-hooks-live):
set `HOOKS_REDIS_URL` (or `TAI_DEFAULT_REDIS_URL`), whatever the worker count. The
backend process raises platform events of its own and matches them against its own
hooks registry; an in-memory one there holds none of the hooks registered through
the server, so those events would run no hook. `tai serve`, `tai backend`, a config
reload and a config write all refuse a `backend_module` over an in-memory hooks
registry.

## Three ways a tool runs off the request path

* **Background** — submit a tool run and poll its result, for a run that outlives
  one request. The background tool-runs HTTP surface loads as a router module.
* **Scheduled** — schedule a tool to run later or on a cadence. A schedule names
  the base `tool_name`, its `tool_kwargs`, and a typed `cadence` (an interval or a
  crontab). The tool must carry the backend's `schedule_task` extension to be
  scheduled on a cadence — see the [schedule-a-tool guide](/guides/schedule-a-tool)
  for attaching it.
* **Distributed** — the worker backend spreads runs across workers.

Manage schedules from the CLI:

```bash theme={null}
tai schedules list
tai schedules add report --cron '0 9 * * *'
tai schedules delete <name>
```

## The job budget

Every backend bounds a dispatched job by one setting, the dispatch group's
`task_timeout` (`<PREFIX>_TASK_TIMEOUT`, 300 seconds by default): it is the longest a
job may run on the worker, and how long a synchronous dispatch waits for its result.
It covers every job the worker runs — a dispatched task, a schedule fire, a callback.
Celery applies it as `task_time_limit`, RQ's worker sets it as the timeout of every job
it runs (whatever timeout the job was stored with), and arq as the worker's
`--job-timeout` default. The worker binds it when it starts, so a change converges
through a process recycle.

A backend never retries a tool body. A tool that wants retries declares a
[`ToolRetryPolicy`](/concepts/tools-and-extensions#retrying-a-tool-call), applied by
the platform's dispatch seam on every door. What a backend still retries is its own
transport — publishing a message on connection loss, reconnecting to its broker.

## Writing a scheduling backend

The scheduling protocol is declared once, in `tai42_contract.backend.scheduling` (also
re-exported by `tai42_kit.backend`). A backend that implements it is a scheduling backend
the schedules door, the CLI, Studio and backups work with unchanged:

* **The tools.** Register `backend_list_schedules` and `backend_delete_schedule` (their
  presence marks scheduling as available), and the backup pair
  `backend_export_schedules` / `backend_import_schedules`.
* **The extension.** Register a `schedule_task` `BACKEND` extension that branches a tool
  into `<tool>_schedule_task`. The door dispatches that branch with the schedule's name
  under `backend_schedule_name` and the dumped `ScheduleCadence` under `backend_schedule`;
  validate it back with the contract's `ScheduleCadence`.
* **The shapes.** The list tool returns `ScheduleListRow` dumps (name, tool, cadence,
  enabled, next run, an optional `error` — never the stored arguments); export returns
  `ScheduleRecord` dumps; import takes `ScheduleRecord` rows and a `skip`/`overwrite`
  mode and returns a `ScheduleImportReport`, reporting a bad row in its `errors` rather
  than dropping it.
* **Your own keys.** A queued job carries the target tool under your backend's own
  tool-name key. Split it out into the record's `tool` on export and list, and inject it
  back on import; the platform reads only `tool`.
* **What you cannot honour, refuse.** A backend that cannot honour an interval's
  `relative` flag refuses it on create, update and import with a clear error.

`tai42_kit.utils.runtime.normalize_schedule` parses the friendly specs a backend's own
tools may accept (seconds, a crontab string, `{"type": "interval", "every": 5, "period":
"minutes"}`) into the contract's cadence.

## Routing a tool to a backend

A tool is routed to a backend with a `BACKEND`-kind
[extension](/concepts/tools-and-extensions) — the extension kind whose job is to
send a tool's execution through a backend rather than running it inline. The tool's
definition does not change; the extension decides where it runs.

> [!WARNING]
>
> A tool that depends on a managed `stdio` MCP server's tools runs on the ASGI, arq,
> and RQ execution paths, but not inside a Celery **prefork** worker child: the
> managed server's live stdio subprocess connection does not survive the prefork
> fork, so those tools are unavailable there. Route such a tool to a non-prefork
> engine, or run it inline on the request path.

> [!NOTE]
>
> A persist-across-jobs backend — a Celery **prefork** pool, whose forked children
> hold their own in-memory caches for the life of the child — turns its pool over
> **once** after any template-eviction or registry-mutating fleet op reaches it over
> the [worker bus](/concepts/worker-bus), so a child never keeps serving a stale
> compiled template or a stale registry from before the change.

> [!NOTE]
>
> A specific worker backend's setup — its broker, queues, and concurrency — lives in
> that backend package's own repository, reachable from the
> [Plugins section](/plugins). The platform documents the backend contract,
> not any one engine.

See the [schedule-a-tool guide](/guides/schedule-a-tool) and the
[HTTP API reference](/reference/api/index) for the tool-run and schedule routes.


# Classifiers
Source: https://docs.tai42.ai/concepts/classifiers

The classifier model type: typed questions about JSON state, typed answers with probabilities.

A **classifier** is a model type that sits beside chat models and embeddings. Where a
chat model writes text and an embedding model turns text into vectors, a classifier
*judges*: it reads a JSON-compatible **state**, answers a set of **typed questions**
about it, and returns one **typed answer per question** carrying a probability. It is
JSON in, JSON out — no free text, no tool calls, no conversation.

The classifier contract is provider-agnostic. The platform ships the shape of a
request and a response; a provider adapts that shape to its own wire format behind
the factory, so a flow or a tool reads and constructs a classification the same way
whichever provider is configured.

## The three question kinds

Every question is one of three kinds, chosen by its `type`. Each carries free-text
`instructions` and, optionally, `criteria` that pin down what the outcomes mean.

* **`noul`** — a binary judgment. The classifier returns the **probability, from 0 to
  1, that the answer is yes**. Optional `criteria` describe what a true and a false
  answer mean. For example, over an inbound **event**: *"Is this event urgent?"* →
  `0.82`.
* **`choice`** — a categorical judgment. `criteria` is a fixed set of labels, each
  mapped to a description; the classifier picks **one label** and reports a
  **probability for every label**. For example, over an **account**: *"Which status
  fits?"* with labels `active`, `dormant`, `closed` → `active` at `0.7`. The labels
  are the question's allowed set, and the platform enforces it (see
  [Answers stay inside what the request declares](#answers-stay-inside-what-the-request-declares)).
* **`score`** — an ordinal judgment. `criteria` is an **ordered rubric** of two or
  more levels; the classifier returns the **expected value** over that rubric plus the
  per-level distribution. For example, over an **alert**: *"Rate the severity"* over
  `["low", "medium", "high", "critical"]` → an expected score of `2.4`.

## A request and its response

A **request** pairs the state with a named mapping of questions — the name is the
author's key for that question:

```json theme={null}
{
  "state": { "subject": "quota exceeded", "retries": 5 },
  "questions": {
    "urgent": { "type": "noul", "instructions": "Is this event urgent?" },
    "status": {
      "type": "choice",
      "instructions": "Which account status fits?",
      "criteria": { "active": "in normal use", "dormant": "idle", "closed": "ended" }
    },
    "severity": {
      "type": "score",
      "instructions": "Rate the severity.",
      "criteria": ["low", "medium", "high", "critical"]
    }
  }
}
```

The **response** carries one answer per question, keyed by the same name, plus the
model that answered, token usage, and the provider's request id. Each answer names
its kind in a `type` discriminator:

```json theme={null}
{
  "model": "jev-latest",
  "answers": {
    "urgent": { "type": "noul", "noul": 0.82 },
    "status": {
      "type": "choice",
      "choice": "active",
      "probabilities": { "active": 0.7, "dormant": 0.2, "closed": 0.1 },
      "confidence": 0.7
    },
    "severity": {
      "type": "score",
      "score": 2.4,
      "legend": { "0": "low", "1": "medium", "2": "high", "3": "critical" },
      "probabilities": { "0": 0.05, "1": 0.15, "2": 0.4, "3": 0.4 },
      "confidence": 0.6
    }
  },
  "usage": { "input_tokens": 120, "output_tokens": 30 },
  "request_id": "…"
}
```

A `noul` answer carries just its `noul` probability; a `choice` answer carries the
chosen `choice`, the per-label `probabilities`, and a `confidence`; a `score` answer
carries the expected `score`, the level `legend` and `probabilities` keyed by level
index, and a `confidence`. Either token count may be unreported.

## Answers stay inside what the request declares

A request declares a set of answers it will accept, and the platform checks every
response against it, whatever the provider:

* **The questions.** The answers are keyed by exactly the request's question names, one
  answer per question, and each answer is of its question's kind.
* **A `choice` question's labels.** The labels are the keys of its `criteria`. The
  chosen `choice` must be one of them, and the `probabilities` must be keyed by exactly
  the labels, one probability per label.
* **A `score` question's levels.** The levels are `0` up to one less than the number of
  rubric entries. The `legend` and the `probabilities` must be keyed by exactly the
  levels, and the `score` must lie between the first and the last level.

A response outside any of these never reaches the caller: the call fails with a
`ClassifierAnswerError` naming the question, what the provider gave, and what the request
declared. Its error kind is `upstream_error`, because the request was valid and the
provider broke the contract. A caller, a tool, or a flow can therefore read every answer
as its own question declared it, without checking it.

## Configuring a classifier

A deployment picks its classifier provider with the `LLM_PROVIDER_CLASSIFIER`
selector — the third model-provider selector beside `LLM_PROVIDER_LLM` and
`LLM_PROVIDER_EMBEDDING` — which defaults to `typesafe`. The provider's connection
details ride the `CLASSIFIER_*` namespace: `CLASSIFIER_MODEL` (default `jev-latest`),
`CLASSIFIER_BASE_URL`, `CLASSIFIER_API_KEY`, and `CLASSIFIER_TIMEOUT`. The full field
table is in the [settings reference](/reference/settings#classifiersettings), and the
[config and secrets](/concepts/config-and-secrets#model-providers) page covers the
provider selectors.

The classifier provider ships as an optional dependency. The `classify` tool pulls it
in through the `classifier` extra — install it with `pip install
'tai42-toolbox[classifier]'`, which brings the kit's `typesafe` provider along.

## Where classifiers are used

* **The `classify` tool.** The standard toolbox exposes classification as a tool any
  caller can run — see the [`classify` walk-through](/guides/standard-toolbox#judge-state-with-classify).
* **The Classifier card in the Studio.** A [Babelfish Flows](/babelfish#judging-with-a-classifier)
  flow can judge its input with a [Classifier card](/babelfish/studio#the-classifier-card),
  whose answers feed downstream conditions.
* **The Router card's classifier backing.** A [Router](/babelfish#decided-by) can be
  [decided by a classifier model](/babelfish/studio#the-router-card) instead of an LLM
  agent, asking one yes/no question per kind and routing on the probability.
* **The kit factory.** In Python, `get_classifier` (and `get_classifier_async`) build
  a cached, provider-keyed runnable that takes a request and returns a response — see
  the [Python SDK reference](/reference/python-sdk/kit-llm#get_classifier).

See the [standard toolbox guide](/guides/standard-toolbox) for running `classify`, the
[Babelfish Flows page](/babelfish#judging-with-a-classifier) for judging inside a flow,
and the [settings reference](/reference/settings#classifiersettings) for every
`CLASSIFIER_*` field.


# Client conversations
Source: https://docs.tai42.ai/concepts/client-conversations

Route a client message from a messaging channel or an API caller to an agent run or a tool dispatch and deliver the answer back.

The conversation bridge turns an inbound message — from a messaging channel like
WhatsApp, Telegram, or Slack, or from an authed API caller — into a turn whose answer
is durably stored and delivered back to the client. One routing table binds each
inbound identity to what answers it — an **agent** run or a direct **tool** dispatch
— and the key that turn runs as.

## The two doors

A message reaches the bridge through one of two doors, chosen per route:

* **`channel`** — a messaging provider's webhook delivers an inbound message. The
  route is matched by the `(channel, our_identity)` pair — the registry name of the
  channel and the medium address the client texted (a phone number, a chat, a Slack
  conversation). The answer is delivered back through the same channel's adapter,
  sent **from** the identity the client texted.
* **`api`** — an authed caller `POST`s to
  `/api/conversations/{route_name}/messages`. The answer is delivered by a signed
  HTTPS callback to the route's `callback_url` when it declares one, returned inline
  on a bounded sync wait, or read back from the poll door when it declares none.

A blank or whitespace-only message is refused before any turn runs: the `api` door
answers `400`, and a channel drops it (logged, nothing sent back).

An authed integration can also deliver a **structured event** into an existing thread
through the [event door](/reference/conversation-bridge#the-event-door): the event
enters that thread as a turn, ordered behind any in-flight message on the **same
per-thread FIFO** an inbound message takes, and its answer is delivered by the target
route's own door. An event carries no human text — it runs a `tool` target only — and
never mints a thread; it always joins one that already exists.

## The routing table

A **route** is one row in the conversation routing table. It binds an inbound door
to what a turn runs — an agent or a tool — and the execution key that turn runs as:

| Field | Meaning |
| - | - |
| `route_name` | A slug (`[a-z0-9-]+`); the handle and the thread-key namespace. |
| `door` | `channel` or `api`. |
| `target_kind` | `agent` (a threaded agent run) or `tool` (a stateless tool dispatch). |
| `target_name` | The agent or tool the turn runs — it must exist. |
| `execution_key` | The API-key identity the turn runs **as**. |
| `initial_mode` | The default [control mode](#control-mode-and-operator-messages): `agent` (run the turn) or `manual` (suppress it for an operator). |
| `start_expr` / `reply_expr` / `cancel_expr` / `resume_expr` / `extras_expr` | Either target kind: jq mapping the message to the run's kwargs, the result to the reply, and driving the run's [parked interactions](/concepts/asking-the-caller). |
| `channel` / `our_identity` | `channel` rows: the registry name and the address texted. |
| `callback_url` | `api` rows, optional: the HTTPS answer sink; without one, answers are read from the poll door. |
| `overlap` | The [overlap policy](#when-messages-overlap): how a running turn treats newer messages on the same thread — leave it, cancel it, or carry a burst into one turn. The default leaves each message its own turn. |

A `channel` route's `(channel, our_identity)` pair is unique — a second route
claiming the same identity is refused at write, so every inbound message resolves
to exactly one route. Many rows may share one channel, each with its own identity,
so one provider account fans out to many targets.

Manage the table from the [Studio Conversations screen](/studio/screens#conversations),
the `tai conversations` CLI, or the `/api/conversations` routes; see the
[bridge reference](/reference/conversation-bridge).

### Agent and tool targets

A `target_kind` of **`agent`** runs a registered agent as the turn: it streams on the
route's thread, so the conversation carries memory across messages. A `target_kind`
of **`tool`** dispatches a registered tool **statelessly** — no conversation memory,
one message in and one reply out. **Either** kind carries the route's optional jq
programs shaping the call:

* **`start_expr`** maps the inbound payload `{message, sender, our_identity,
  channel, route, turn}` to the run's kwargs — a tool's kwargs, or an agent's `astream` kwargs;
  without it a tool gets those six keys (plus `event` on an event turn) and an agent reads
  the rendered turn text.
* **`reply_expr`** maps the run's result to the reply text; without it a tool result
  must itself be a string or `null`. It only ever sees a **returned** result: a
  run that fails (a flow's `error`, `stopped`, or `aborted` terminal among them)
  skips the mapping and resolves as the `error` outcome instead, whose text is the
  target's reply when the failure carries one, else the route's error reply
  ([failure replies](/reference/conversation-bridge#failure-replies)). It also
  binds `$turn`, `$asks`, and `$parked` (see [jq variables](/concepts/jq-variables#route-reply)).
* **`cancel_expr` / `resume_expr` / `extras_expr`** — the [door
  contract](/concepts/asking-the-caller#the-door-contract) driving the run's parked
  interactions, each reading `$parked`.

The payload also carries a **`params`** object when the inbound entry supplied one —
a web-channel visitor's [link parameters](/plugins/tai42/channel-web#link-parameters),
the API message door's `params` field, or a channel's **tap enrichment** when a person
taps a control the flow offered: the tapped reply's author-set `id` arrives as
`params.reply_id` (a sectioned row's `description` as `params.reply_description` where
the medium carries it), a template quick-reply as `params.button_payload`, a
click-to-chat entry as its `referral_*` fields. All are string values reachable as
`.params.<name>`, present only when non-empty. They are untrusted transport the
platform caps and delivers but never signs or interprets; a value a flow must trust is
a secret the flow checks in its own store.

This is the **bridge-path** counterpart of the enrichment an
[answer](/concepts/interactions#enrichment-on-the-answer) carries: when a tap
**answers** a pending `ask` its context rides the answer's `params`, and when the
same tap is instead **bridged** as a fresh turn (no pending ask, or a `bridge`-policy
digression) it rides this payload `params` — the same enrichment on either arm, never
dropped.

A tool reply that is `null` or blank is a **deliberate silence** — the turn ran but
has nothing to say. On a `channel` route nothing is sent back (a terminal `silent`
record); on an `api` route the silence is communicated, delivered as a callback (or
sync-wait reply, or a poll-door record) whose `status` is `silent` and which carries no answer text. That
makes a tool target a way to answer some messages and stay quiet on others: a
published [flow preset](/concepts/presets), say, that replies only when it has
something to return. See the [bridge
reference](/reference/conversation-bridge#route-targets-agent-or-tool) for the exprs
in full.

A `tool` target may also carry a
[`state_binding`](/concepts/states#a-bindings-subject-and-scope), so the route injects a bound
state's `input` values into the dispatch and applies its `update` afterward — a binding applies
to tool targets (a registered preset or a plain tool). An `agent` target takes no binding: a
route with `target_kind: agent` that carries a `state_binding` is refused at save (`400`).

A tool or flow target need not answer in one synchronous step either. Like an agent
target, its turn can async-park on an `ask` — pausing for a person's answer or
its expiry — and deliver its resumed reply back into the originating thread later,
mapped through the route's reply mapping.

A run may also [ask its caller](/concepts/asking-the-caller) (`to="caller"`) rather
than a person. When a turn asks its caller instead of finishing, its `reply_expr` sees
those asks in `$asks` and maps them to the reply, and the route's `resume_expr`
resolves them on the next visit — the [door
contract](/concepts/asking-the-caller#the-door-contract) in full.

### Structured participant messages

A participant message is always **text first**. When an inbound message carries a
structured object — an [ask-less form](/concepts/notifications#ask-less-forms)'s
submission — the text is a faithful rendering of the submission and stays the whole
turn every consumer sees: an `agent` target reads the text only, the transcript
records the text, and a form-unaware route behaves exactly as before. The structured
copy rides **beside** the text: a `tool` target's payload carries it under a `form`
key, present **only** when the inbound carried one, so an existing `start_expr`
sees a byte-identical payload for a form-less inbound — a route maps the form
deliberately or not at all. The answer record keeps the object as `inbound_form`,
published on the admin and caller-safe reads alike.

The values are **untrusted participant data**: the platform bounds them as pure transport
(a serialized-size and nesting cap) and never validates them against the form's
schema — a submission is exactly as trustworthy as typed participant text, so a tool that
consumes one validates what it reads. The API [message door](/reference/conversation-bridge#the-message-door)
accepts the same shape: a `form` object beside the required `text`, under the same
bounds.

An inbound message may carry three more structured siblings the same way — **beside**
the text-first turn, delivered to a `tool` target's payload only when present:

* **`attachments`** — a list of `MediaItem`s the person sent with the text
  (image/document/video/audio), the inbound counterpart of an outbound answer's
  `media`. It rides under an `attachments` payload key.
* **`location`** — a geographic point the person shared, a `LocationElement`
  (latitude/longitude with an optional name/address). It rides under a `location`
  payload key.
* **`reply_to`** — the earlier message this one replied to, as the platform resolved it
  from the conversation's own records: `{message_id, status, text}`, the quoted text when
  it is held. It rides under a `reply_to` payload key. See [replies to an earlier
  message](/reference/conversation-bridge#replies-to-an-earlier-message).

All three follow the `form` pattern exactly: the `text` stays the whole turn every reader
(and every `agent` target) consumes, the structured copy is delivered only to a
form-/media-aware `tool` route, and a form-less, attachment-less, location-less
inbound that quotes nothing is byte-identical to the pre-vocabulary payload. The values are the same
untrusted, transport-bounded participant data. A quote's `text` is the platform's own
record of the earlier message, not text the person sent with this one.

> [!NOTE]
>
> On some channels an inbound attachment bridges as **params** rather than a typed
> `attachments` entry — WhatsApp, for one, forwards an inbound media message with its
> identity under `params.media_kind` / `params.media_id` (the Graph media id is not a
> durable served-media source, so a consumer re-fetches the bytes with operator
> credentials). An inbound **location** on that channel does land as a typed
> `location`. What each channel bridges is documented on its
> [plugin page](/plugins).

### The person's locale

A conversation carries a **locale** — a BCP 47 language tag (e.g. `he-IL`) the platform's
[rendering layer](/concepts/storage-and-resources#locale-variants) resolves every template and
list format against. The caller states the language; the flow never selects one, and a `null`
locale means none is known (never a silent default).

* **`ConversationMessage.locale`** — the participant's per-message language hint the channel resolved
  from its native inbound, carried beside the text (and accepted on the API message door). It
  seeds a first-contact person's stored locale and, absent a stored override, is the turn's
  resolved locale.
* **the person's stored `locale`** — the operator override held on the [`Person`](/concepts/client-conversations)
  row, seeded from the channel at first contact and canonical in storage. Set or clear it through
  `PUT /api/conversations/persons/{person_id}/locale` (the same write grant that forgets a thread)
  or the CLI's [`tai conversations set-person-locale`](/reference/cli/conversations) / read it with
  `tai conversations get-person`. A later turn never clobbers a stored override.
* **the subject `locale`** — the locale captured onto each turn's subject, resolved by
  precedence: the person's stored locale (operator override or first-contact seed) wins, else the
  message's per-message hint, else the route's default `locale` (`--locale`), else `None`. It is
  what the renderer reads for every template and the `list_format` filter.

A locale change while the person is being erased answers `503`, and nothing changes.

### Rich, multi-message answers

A `tool` target need not answer with a single string. Its `reply_expr` (or, with no
expr, the tool's own result) may emit an ordered **array of parts** — each element
either a plain string (a text-only message) or an object carrying `message` with the
same rich forms a [notification](/concepts/notifications#what-a-notification-carries)
carries: `media` (image/document/video/audio files with an optional document
`filename`, plus links), a shared `location`, tappable `options`, a sectioned
`sections` list, a media `header` and text `footer`, a pre-approved `template`, or an
[ask-less form](/concepts/notifications#ask-less-forms)'s `schema`. A form part may also
carry the same per-send [`data` and `pages`](/concepts/interactions#prefilling-per-send-options-and-pages)
an ask does — `data.values` prefills top-level properties, `data.options` supplies a per-send
choice list, and `pages` lays the form out in titled steps — so a reply part can open its form
already filled in and stepped. `data`/`pages` ride ONLY a form part (a part carrying `schema`);
on any other part they are refused, and on a form part each is cross-checked against that part's
`schema` before delivery. The delivery
machine sends each part as its own message in order, so one turn can reply with
several bubbles, attach a document, share a pin, or offer tappable options. A part may
be **content-only** — an object with `media` or `location` and no text — for a
caption-less image or a bare pin. The array is strict: an unknown key or an empty
array is a loud error, never silently coerced, and each part obeys the same
[composition rules](/concepts/notifications#what-a-notification-carries) (`options`
XOR `sections`; `schema` excludes both; `header`/`footer` require a choice surface;
`template` stands alone) and the same per-channel
[capability gate](/concepts/notifications#channel-capability-matrix) — a channel
without the matching capability never receives the field. Each part is also held to
the same channel checks a notification gets — a `template` part to the channel's own
template-parameter check, a `schema` part to the channel-renderable subset and then the
channel's own form limits — once per part, before any part of the reply is sent. A part
that fails fails the whole reply: nothing of it is sent, the end user is told the route's
`reply_texts.error` (else the built-in notice), the refusal is logged naming the property,
parameter or limit, and the record shows `failed` in the admin failed-delivery listing.

`options` are the same **typed** shapes a notification uses — a `reply` (its `text`
becomes the person's next message; an author-set `id` echoes back on the next turn's
`params.reply_id`, and a `description` renders as a row's secondary line) or a `link`
(opens its `url`, submits nothing). A `template` carries its **named components**
(`header_media`, `body_parameters`, `buttons`) — the old flat `parameters` list is
**removed**.

Every reader that consumes a single answer string keeps working unchanged. The parts'
non-blank message texts are joined with a blank line into the same `answer` an `api`
callback, a bounded sync-wait, or a transcript reads, while a parts-aware consumer
reads the ordered parts and delivers each on its own. An `agent` target stays
single-string — ordered multi-message answers come from tool routes, which carry an
explicit reply contract.

## How a route is authorized

Two authorities are separate and both live:

1. **Who may send.** A `channel` message is authenticated by the provider's own
   signature over the raw webhook body (fail-closed — an unsigned or mis-signed
   delivery is rejected and runs no turn). An `api` message is authenticated by the
   access-control gate on the send door: the caller needs a key authorized for that
   route.
2. **What the turn may do.** The turn runs as the route's bound `execution_key`,
   **not** as whoever sent the message. That key's live stored grants authorize the
   agent run (or the `tool` target's dispatch) and every tool call the turn makes.

Binding the execution key is a delegation decision taken when the route is created:
you may bind your own identity or a key you own, or any key as an admin (a
pass-role check). The key must be evaluable by a background execution — its stored
policy condition must be resolvable with no request token — or the bind is refused.

Because the turn is authorized against the key's **live** grants at fire time, you
revoke a route's authority by attenuating its key: drop a scope, disable it, delete
it, or narrow its owner, and the very next turn is denied. There is no
revocation-specific step. Scope the execution key (or the agent) to least privilege
— the turn can do exactly what that key can do, no more.

> [!WARNING]
>
> A `public` trigger-auth hook can be fired by **anyone, with no credential** — so the
> bound `execution_key` is the **only** thing bounding what a fired hook can do. Treat the
> key as the security boundary: bind a **least-privilege** key, and **never** bind an admin
> or broad key to a `public` (or `token`) hook — that lets any caller act with those
> privileges. Use `verifier` or `api_key` triggers when the fire itself must be
> authenticated.

## The round trip

```mermaid theme={null}
flowchart LR
    C["client<br/>(WhatsApp / API caller)"] -->|inbound| CH["channel webhook<br/>or api door"]
    CH -->|match route| BR["bridge<br/>(routing table)"]
    BR -->|run AS execution_key| AG["agent run<br/>or tool dispatch"]
    AG -->|answer persisted| REC["answer record"]
    REC -->|deliver| OUT["channel send<br/>or signed callback"]
    OUT -->|reply| C
```

The inbound door returns as soon as the message is accepted and its answer record
persisted; the turn runs in the background and the answer is delivered when it
completes. A `channel` door returns the accepted id immediately; the `api` door
returns `202 {message_id, thread_id}`, or — with a bounded `wait_seconds` — `200`
carrying the answer inline when the turn finishes in time (a route with a callback then
suppresses it so it never double-fires). A route with no `callback_url` records the answer
for the poll door, `GET /api/conversations/{route_name}/messages/{message_id}`.

## Answer outcomes

Every accepted message gets a durable **answer record** that moves through a
delivery lifecycle:

* `accepted` — admitted, turn not yet complete (carries no answer).
* `pending_delivery` — the turn's answer is persisted and awaiting send; this is
  what a restart re-drives.
* `provisional` — sent, awaiting an out-of-band delivery receipt or a grace
  timeout.
* `delivered` — confirmed.
* `failed` — undelivered after the attempt budget, reported failed by the
  provider, or a delivery row the sweep can never parse (loud, retained, and listed on the
  admin failed-delivery door).
* `shed` — refused by the address rate cap; no turn ran.
* `silent` — nothing is sent back for the inbound. It arises two ways: a **channel**
  `tool` turn whose mapped reply was `null` or blank, or a `manual`-mode inbound whose
  suppressed target turn produced no reply (see [control
  mode](#control-mode-and-operator-messages)) — a due pairing reply or first-contact
  greeting is sent instead, so those are *not* silent. On an **api** route the silence is
  communicated instead — the record ends `delivered`, its callback carrying
  `status: "silent"` and no answer.
* `merged` — this message's text was carried into the turn named by its `successor_id` under an
  [overlap policy](#when-messages-overlap) (`deliver: all`).
* `superseded` — this message was dropped in favour of the turn named by its `successor_id` (a
  running turn cancelled by a newer message, or a queued message overtaken by a newer one on a
  `cancel` route).

`merged` and `superseded` are answerless terminal outcomes that name the turn that took the
message's place through a `successor_id`. On a **channel** route they are terminal and send
nothing; on an **api** route they are delivered as a marker exactly as `silent` is — the
callback carries the `status` and `successor_id` with no answer text.

A turn's own outcome is orthogonal: `answered`, `error`, `silent`, `merged`, or `superseded`
— an `error` answer carries the failing target's own reply when its failure carries one,
else the route's `reply_texts.error`, else the built-in line, and the platform never puts an
internal detail into it ([failure replies](/reference/conversation-bridge#failure-replies)); `silent`,
`merged`, and `superseded` carry no answer text at all, and `merged`/`superseded` name their
`successor_id`. Delivery is retried
with backoff; a permanently undelivered answer ends `failed` rather than
disappearing.

Late failures surface too: a channel can send a `2xx` and then a `failed`
delivery-status webhook (a message rejected outside WhatsApp's 24-hour service
window arrives this way), which flips the record to `failed`. A route can see that
window before it replies: every turn carries it as
[`turn.reply_window`](/reference/conversation-bridge#route-targets-agent-or-tool)
(`open` with its close time, `closed`, or `none` where the channel has no window).

## When messages overlap

A participant does not wait their turn. A second message often lands while the turn on the
first is still running. By default the platform keeps each message its own turn, strictly
ordered — the second waits behind the first and then runs. A route's `overlap` policy chooses a
different behaviour, in three knobs — a settle window needs `deliver: all` or `running: cancel` — (the [bridge
reference](/reference/conversation-bridge#overlapping-messages) has the exact fields and how
each outcome is delivered):

* **Know / cancel** (`running`) — `continue` leaves a running turn alone; `cancel` cancels it
  cooperatively in favour of the newer message, which runs instead.
* **Carry** (`deliver`) — `one` runs a turn per message; `all` carries every message accepted
  since the last turn started into one turn, in order.
* **Settle** (`settle_seconds`) — hold a turn back a few seconds after its lead message so a
  burst rides one turn rather than several.

The policy is a generic conversation mechanism: it governs participant message turns only, and
the target — an agent or a tool — needs to know nothing about it. Under `deliver: all` the turn
simply sees the whole burst as its text (and, for a tool target, a `messages` list); under
`cancel` a turn cut short resolves `superseded` and delivers nothing, and its record names the
message that replaced it through `successor_id`.

### The handler can cooperate

Cancellation is **cooperative**: it can only stop a turn at an `await`, so it cannot claw back a
synchronous step already running, and it never reverts state the turn already wrote. Where that
matters, the handler cooperates — any code running inside a turn can read the **pending seam** to
learn a newer message is waiting and yield before an expensive or irreversible step:

* `current_conversation_turn()` returns the turn in flight (its thread and lead message), or
  `None` outside any turn.
* `app.conversations.pending_messages(thread_id, after=<the lead message id>)` returns the
  participant messages accepted after the lead and not yet carried into a turn.

A body that finds something pending stops early by raising `TurnSupersededError(successor_id=…)`
— the same outcome a cancel produces: no reply, no error, no delivery. `TurnSupersededError` is a
`BaseException`, not an `Exception`, so no broad `except Exception` between the yielding body and
the platform's turn runner — which catches it explicitly — ever swallows the yield. Under `running: continue`
this is how a handler implements "the newer message wins": it yields, the next turn runs, and
under `deliver: all` the yielded message rides that turn. The handler picks which steps must not
run past a newer message; the platform stays agnostic to what it does.

## Control mode and operator messages

Every thread runs in one of two **control modes**, and the route carries the default:

* **`agent`** (the default) — an inbound message buys a **target turn**: the agent run
  or the tool dispatch answers it, exactly as [the round trip](#the-round-trip)
  describes.
* **`manual`** — the target turn is **suppressed**. The inbound is recorded but the
  flow does not answer it, so a human answers by hand. The platform's own control
  turns are unaffected: pairing and the first-contact greeting still run.

A route's `initial_mode` is the default; a per-thread override wins over it, so the
mode in force for a thread is its override when one is set, else the route default. A
linked person's aggregated thread with no override defaults to `manual` when **any**
route the person spans sets `initial_mode: manual`, else `agent` — one operator control
decision covers every channel they paired. The override carries the answer records'
retention TTL and is **refreshed on thread activity** — each accepted inbound and each
operator send — so it expires *with* the conversation: a thread that falls quiet past
the retention window loses its override along with its records, and a returning address
starts again at the route default. An explicit thread
[delete](#conversation-lifetime), or a route delete, reclaims it at once.

`manual` is valid for **every** target — a `manual` `initial_mode`, a `PUT
…/thread/mode`, and the `set_conversation_mode` builtin all take it, on a `tool` target
or an agent alike.

In `manual` mode the client gets **no automatic answer** to an ordinary inbound: its
target turn is suppressed, so on a `channel` route the record ends terminal `silent`
and on an `api` route the silence is delivered as a `status: "silent"` marker. The
platform's own control turns are the exception — a pairing action still gets its reply,
and on a multichannel route a due first-contact greeting still runs: it is prepended
onto the otherwise-silent outcome, so **that** record ends `answered` and is delivered
carrying the greeting text. A greeting owed on a turn that is then superseded — cancelled by
a newer message or yielded by the turn body — is never dropped: it is carried to the successor
turn and leads that turn's reply, on every door. Whether the suppressed inbound is **remembered** turns on
the target's memory: a target that keeps thread memory — an agent that implements the
thread-memory append — has it **appended to that memory**, so a later agent turn once
the thread is back in `agent` mode reads it as prior context; a target with no thread
memory — a `tool` target, or an agent without the append — skips the step, its
transcript standing as the record. An append that fails is a loud `error` outcome, never
a silent drop.

Three parties flip the switch:

* **An operator**, on a named thread — the Studio's [Conversations
  screen](/studio/screens#conversations) toggle, `tai conversations mode-set`, or the
  `PUT …/thread/mode` door.
* **The agent itself**, from inside its own turn, with the `set_conversation_mode`
  builtin tool — it flips the **current** conversation (the thread the turn runs on),
  so a flow can hand its own conversation off to a human. The tool reads the live
  thread from the turn context and names none; called outside a turn it refuses loudly.
* **An external system**, through the same `PUT …/thread/mode` door, which names its
  thread explicitly.

### Operator messages

An operator answers a thread **by hand** with `tai conversations send` (the
`POST …/thread/messages` door) or the Studio compose box. No turn runs: the message is
stored already answered and **delivered through the same machine a produced answer
takes** — sent from the route identity, with the same chunking, ledger, and receipts.
An operator reply may itself carry **media**, tappable **options** (the same
[typed reply/link shapes](/concepts/notifications#media-kinds-and-typed-options)), a
pre-approved **template**, or an [ask-less form](/concepts/notifications#ask-less-forms)'s
**schema** — the same rich content a produced answer can — validated up front so a bad
attachment is a clean rejection rather than a failed send. A form the channel cannot draw,
or a template whose parameters the channel cannot map, fails the record before anything is
sent, like a missing capability, with no notice to the end user. It is allowed in
**either** mode and **never flips the mode**.

The record is marked `origin: "operator"` (a client turn's record is `origin:
"client"`): it carries the operator's text as its `answer`, an empty `inbound_text`,
and names the sending operator. For a target that **keeps thread memory** the text is
appended to the thread's memory as an `assistant` reply — the same conditional append a
suppressed inbound takes, mirroring how the agent's own answer enters memory — **before**
the record is created, so a later agent turn reads the operator's reply as prior context;
a target with no memory skips it. An append that fails is loud and no record is created.
Memory stays continuous both ways: a manual-mode inbound the flow never answered and the
operator's own reply both sit in the thread the agent resumes on.

On a linked person's aggregated thread the reply returns to the address they last wrote
from (a message the platform sent them does not count), or to an explicit `address` that
must be one of the person's. Sending is the
door's **write** action — the same grant that creates a route — and an unauthenticated
caller is refused (`501`), since an operator action must be attributable. See [operator
messages and control mode](/reference/conversation-bridge#operator-messages-and-control-mode).

## Watching a route's conversations

Every route's threads and their transcripts are readable while they are retained,
whichever door the messages arrived through. An operator reads them on the Studio's
[Conversations screen](/studio/screens#conversations) — a route picker, a thread
list, and a live-tailing transcript — or from the CLI with
[`tai conversations threads`](/reference/cli/conversations) and
`tai conversations transcript`. A thread listing spans every caller on its route, so
the listing is admin-only; a transcript read takes the same conversations read grant.
See [the read doors](/reference/conversation-bridge#the-read-doors).

The listing narrows with `?status=` (a delivery-status the thread's newest record must
match) and `?address=` (a substring of the thread id's client-address suffix); a transcript
narrows with `?q=` (records whose inbound text or answer contains the substring); and
`GET …/messages/search?q=` searches every record on the route. None has a dedicated index, so
each is a **bounded post-scan** whose envelope carries a `truncated` flag — `true` when a page
spent its scan budget before the route was exhausted, so a client never mistakes a bounded
page for the whole result. See [the read
doors](/reference/conversation-bridge#the-read-doors).

Every listing also reports an `unreadable` count for any stored row the platform could not
decode, so a corrupt row is surfaced as a number rather than dropped from the view.

A transcript page also carries `person_id`: the linked person a `bridge:@person:{person_id}`
thread aggregates, or `null` for a route-keyed thread, so a reader of one open thread knows
whose aggregated history it is (and which person an erase would remove).

Each transcript record carries its `origin` — `client` for an inbound turn, `operator`
for a by-hand reply, `send` for a message the platform sent on its own (a `notify_user`
send, a question, a notice) — so an operator's messages and the platform's sends read as
distinct from the flow's answers. A send made during a turn carries that turn's
`turn_message_id`. See [send records](/reference/conversation-bridge#send-records). From
the same Studio screen an operator can also flip the thread's [control
mode](#control-mode-and-operator-messages) and compose a reply by hand.

## Conversation lifetime

A route's thread key is `bridge:{route_name}:{client_address}`, so each client address
holds its own conversation on a route and an `agent` remembers earlier turns across
separate inbound messages. On any target with multichannel on, a linked person — one
whose sending address is paired to more than one address — instead keys the aggregated
`bridge:@person:{person_id}` thread, so all of that person's paired channels share one
thread; every other sender keeps the `bridge:{route_name}:{client_address}` key.
Continuity is the checkpoint store's: a thread lives the checkpoint waiting retention
(`LLM_PROVIDER_CHECKPOINT_RETENTION_WAITING_MINUTES`, 7 days by default) after its last
message; one idle past it expires and the next message starts fresh. See
[retention](/reference/conversation-bridge#checkpoint-retention).

**Every send is in the thread.** A message the platform sends to a participant — a
`notify_user` send, a question, a notice — is recorded in the same thread an inbound
message from them uses, and may start it. A completed send is placed by the address the
medium reports, so a send to a handle lands in the thread of the address the medium
resolved it to; a send made during a turn to its own participant stays in the turn's
thread. With no conversations store (no `CONVERSATIONS_REDIS_URL`) sends still go out and
nothing is recorded. An event by `thread_id` on a linked person's thread goes where the
person last wrote from; a person thread holding only send records refuses it with a `400`.

An operator can also **forget** one thread outright — its checkpoint, its answer
records, its indexes, and the thread's own [declared state](/concepts/states) — with
[`tai conversations delete-thread`](/reference/cli/conversations) (the
`DELETE …/thread` door), so the next message on that address starts fresh without
waiting for a TTL. A reset is a **complete forget**: the transcript and the
conversation's own declared-state memory both go, and the delete response reports a
`states_erased` count beside `removed`. Forgetting is authorized by the same write grant
that creates the route, and a valid id on its own route always succeeds. See [forgetting
a thread](/reference/conversation-bridge#forgetting-a-thread).

A **linked person** can be erased ENTIRELY with
[`tai conversations delete-person`](/reference/cli/conversations) (the
`DELETE …/persons/{person_id}` door): its aggregated `bridge:@person:{id}` thread (checkpoint,
records, indexes), its [declared state](/concepts/states) — both the person's own cross-thread
memory and the aggregated thread's — its person row, and every address→person index mapping go
together, so the next message from any of its addresses starts as a fresh provisional person.
The erase also clears every thread only the person and the persons it absorbed by a link
wrote in, on every route (a thread another person also wrote in is left to them), and its
answer lists the absorbed persons in `absorbed_person_ids`; erasing an id a `/link` absorbed
is a `409` that names the person it was absorbed into, whose erase clears it.
The erase reports its own `states_erased` count, and it is idempotent — a person already gone is
not an error. See [forgetting a person](/reference/conversation-bridge#forgetting-a-person).

A `tool` target keeps no **conversation** memory: the dispatch is stateless, so no
conversation state is carried across messages and each message is answered on its own. Its thread key
still groups that route's answer records and transcripts and orders its turns; there is
simply no checkpoint to remember or expire. When the target's multichannel is on the
payload carries `person_id` and `person_addresses`, so a tool can anchor its own
continuity on that channel-stable person even though the platform keeps no conversation
memory for it.

Answer records carry their own retention: a record is kept for a retention window
after it reaches a terminal state, then expires with its indexes.

## See also

* [WhatsApp to an agent](/guides/whatsapp-to-agent) — both providers, end to end.
* [Connect your own system](/guides/connect-your-own-system) — the API door.
* [Telegram / Slack to an agent](/guides/telegram-slack-to-agent).
* [One bot, many skills](/guides/one-bot-many-skills) — a relay agent.
* [Conversation bridge reference](/reference/conversation-bridge) — CRUD, doors,
  the authorization model, and every setting.


# Config and secrets
Source: https://docs.tai42.ai/concepts/config-and-secrets

Swappable config and secret providers.

Configuration and secrets back a server's environment and settings. A built-in
file provider ships by default, and the store is swappable behind one contract, so
a server can read its config from a file, from Kubernetes, or from another backend
without any change to the code that consumes it.

## The provider seam

Config is a pluggable-provider feature. The skeleton ships the selection seam — a
config **mode**, its settings, and a factory that maps a mode to a provider module
— and the default file provider. The active mode is chosen with `TAI_CONFIG_MODE`
(`file` by default). The factory loads the selected provider by dynamic import and
builds its manager:

```python theme={null}
from tai42_skeleton.config import ConfigManagerFactory

manager = ConfigManagerFactory.create()
```

Other providers ship as separately installed plugins that expose the same
`build_config_manager()` convention. The factory needs nothing but the mode and the
module; the consuming code never knows which provider is behind the manager.

## Secrets are referenced, not embedded

A sensitive value is referenced by the **name** of the environment variable that
holds it, not by value — the runtime reads it from the environment at use time, so a
file that is edited, versioned, or displayed never contains the credential itself.
The reference takes one of two shapes, by where it sits:

* **A scalar value written `!ENV ${VAR}`** is the convention wherever a secret rides
  as a plain string leaf — a [manifest](/concepts/manifest) value, a Studio secret
  field, and a [preset](/concepts/presets)'s baked `fixed_kwargs`. The runtime keeps
  the marker verbatim and resolves it from the environment at use time; the
  `!ENV ${VAR:default}` form falls back to `default` when the variable is absent. The
  Studio `SecretRefField` and MCP-tab secret flow write this marker for a pasted
  secret automatically (see [Settings profiles](#settings-profiles)).
* **A `secret_env` field** carries the env var name where the binding is a config
  object rather than a scalar — a hook or webhook verifier binding names `secret_env`,
  and an OAuth connector provider a `client_secret_env`.

Either way the credential stays out of every file that is edited, versioned, or
displayed.

## How a config change is written

Every change to the manifest or env — a tool reload, a manifest replace, a live
env edit — runs one [mutation pipeline](/concepts/live-operations#the-mutation-pipeline):
validate the resulting config, persist it transactionally, reload the calling
process, then broadcast on the [worker bus](/concepts/worker-bus). Persisting
before reloading is why the persisted config and the live config cannot drift
apart through a supported path — the running state is always what is on disk.

Two guarantees hold across every provider:

* **Transactional writes, in both config modes.** A write holds exclusive access
  across the whole read-modify-write span, so a concurrent writer cannot
  interleave and lose an update — the `file` provider takes a lock, the `kubernetes`
  provider retries on an optimistic-concurrency conflict.
* **Comment preservation.** A manifest edit keeps the surrounding comments,
  key order, and formatting of the untouched document. An automated edit does not
  reflow a file a human maintains by hand.

## Settings profiles

A **settings profile** is a named, versioned snapshot of the whole profile-managed
env band — its env map, the per-key secret marks, and a description — kept in the
same versioned-document store as [presets](/concepts/presets). Applying a profile
**replaces** the stored env with its band in one shot: a key the profile does not
name is dropped (save the carried deployment band, below), so a profile is a whole
environment you switch to, not a patch you layer on. The profile's secret marks are
written with it, so a key it marks secret stays masked once applied. Drive it from the CLI:

```bash theme={null}
tai config profile diff production
tai config profile apply production
```

![The Studio Profiles tab showing a saved settings profile whose secret-marked key is masked.](https://mintcdn.com/tai42/KvPXlWX1hf_jvQ8U/images/studio/profiles-light.png?fit=max\&auto=format\&n=KvPXlWX1hf_jvQ8U\&q=85\&s=767a7dd4959556d7ada9a11722555703)

The Profiles tab: a saved profile's env band, with its secret-marked key masked.

An apply runs the same [mutation pipeline](/concepts/live-operations#the-mutation-pipeline)
as every other config change — validate, persist, reload, broadcast — so the whole
fleet converges and the response carries the
[fleet report](/concepts/worker-bus#what-the-fleet-report-tells-you).

**Only `!ENV` references follow the profile.** A profile switches the
profile-managed env band, not the manifest document, so what a profile can switch
inside the manifest is exactly its `!ENV` references. A manifest value written as
an `!ENV ${KEY}` reference resolves against the effective env at reload — switch to
a profile that changes `KEY` and the value resolves differently. An **inline**
(literal) manifest value is baked into the manifest document, not the env band, so
no profile touches it and it is not switchable. This is why the Studio
`SecretRefField` / MCP-tab secret flow writes an `!ENV` reference automatically: a
pasted secret is stored under a generated env key and the manifest gets the marker,
never the plaintext — so a secret is
[referenced, not embedded](#secrets-are-referenced-not-embedded), stays masked, and
stays profile-switchable.

**Stored env applies at boot, before anything resolves.** Every serving process
bridges the stored env — the config store's `.env` or the Kubernetes Secret — into
its environment at boot, before the manifest resolves, at the same precedence as a
reload: a stored value overrides the container env. So an `!ENV ${KEY}` marker
resolves to its stored value on a cold boot, not only after a later reload. A marker
whose variable is set in neither the container env nor the stored env resolves to a
sentinel, and boot emits one loud warning naming the dangling variables.

**Reload classes.** Every setting carries a reload class, surfaced in the
[settings reference](/reference/settings). Every env write — a profile apply, an env
edit (`tai config env set`, the Studio editor), a backup import, and the marketplace
and MCP-secret writes — diffs the env it would store against the stored one and
classifies each changed key by its class; a key re-sent unchanged is not a change:

* **hot** — re-read in place on the next serving generation. The common case; no
  resource is torn down.
* **recycle** — the pooled resource behind the key (a Redis or broker connection,
  the bus) must be torn down and rebuilt, which needs a supervisor that can respawn
  the affected process (see per-shape support below). Every env write rolls that
  recycle across the fleet wherever the shape can carry it and refuses the change
  where it cannot. A recycle-class value changed in the stored env outside these
  writes (a hand edit of `.env`, a `kubectl edit` of the config Secret) is named by
  the next reload — each worker's `awaiting_respawn` — and takes effect when the
  process is respawned. A worker compares each recycle-class value with the one it
  bound — at boot, or when the plugin that declares the setting was loaded — so a
  plugin loaded after boot with its value already in place awaits nothing. The response of an env write or a profile apply names under
  `awaiting_respawn` the workers (name and keys) still awaiting a respawn after its
  roll — empty when the roll converged.
* **excluded** — deployment / boot identity: the config mode, the transport, the
  manifest path, the readiness sentinel. These are set by the launcher and have no
  live-reload path, so a profile that carries one is **refused** — at save and at
  apply — naming the key. The refusal reads the profile's declared keys, never the
  effective env, so the applier legitimately carrying the whole excluded band across
  the replace is not itself rejected.

**Key material is refused, not carried.** Key material — KEKs and signing keys
such as `CONNECTORS_KEK`, the `KeyMaterial` type — is flagged apart from the reload
classes. A profile (or env edit, or backup import) that **names** a key-material key
is **refused** — at save and at apply — naming the key and pointing at its rotation
path, because bulk-setting one would silently invalidate every secret the old key
secured. Key material is rotated only through its own controlled path, never set
through a profile. Like the excluded refusal, this reads the profile's declared keys,
never the effective env, so an applier legitimately carrying the stored key material
across the replace is not itself rejected. For `CONNECTORS_KEK` that controlled path is
[Rotating `CONNECTORS_KEK`](#rotating-connectors_kek): rotate the key with a
previous-key decrypt ring plus a re-encrypt sweep, so old ciphertext is never bricked.

**`@previous` revert.** Every apply first snapshots the current stored env into a
reserved `@previous` profile *before* it writes, so the last-known-good environment
is always one apply away — `tai config profile apply @previous` reverts a bad
change. Names beginning `@` are reserved for these pipeline snapshots; an operator
cannot create or overwrite one, and they are hidden from the profile list.

**Per-shape recycle support.** Whether a recycle-class change can be carried depends
on the **deployment shape**, which the server reads from a supervision marker set in
lockstep with the config mode. The refusals below hold on every env write — a profile
apply, an env edit, a backup import — and name the keys, with nothing written:

* On a **supervised** shape (Kubernetes, Compose, the e2e harness) the recycle
  rebuilds the affected pooled resource, and the response of every env write — a
  profile apply, `tai config env set`, a backup restore, a plugin install — carries
  the recycle rows naming which workers recycled. The worker that took the write
  recycles itself after replying, through whichever door the write came: the HTTP
  response, or a tool call (MCP `tools/call`, `tai tools run`, an agent, a preset, a
  schedule, a hook). The exit is graceful, so the reply finishes before the worker
  stops and its supervisor respawns it. When the write runs inside a backend job (a
  schedule fire, a tool queued on the backend with an `async_task` branch, a hook
  dispatched through the backend), the backend worker that ran the job is the one that
  took the write: it finishes that job, records its result, and then exits. A
  background tool run (`POST /api/tool-runs`) runs on the serve worker that took it, so
  that serve worker recycles once the run has ended.
* On a **bare** shape — no supervisor — a recycle-class change is refused wholesale:
  nothing can respawn the process, so the change could never converge, and saying so
  upfront beats a half-applied surface. The refusal names the way out: set the key in
  the deployment's environment (or the stored `.env`) and restart the server, or run
  under a supervised deployment, where a recycle carries it.
* Even on a supervised shape some keys are **pinned by the deployment itself**. A
  Compose anchor key (`x-tai-app-env`) or a Kubernetes pod-env value is owned by the
  deployment. The stored env overrides the container env at every boot and reload, so a
  stored copy of such a key, written by a profile or an env edit, would shadow the
  deployment's value on every restart, and a later change to it in the deployment
  manifest would silently stop taking effect. The deployment **declares** the keys it pins in
  `TAI_SUPERVISED_PINNED_KEYS` — a JSON list of env names set beside the
  `TAI_SUPERVISED` marker (the shipped Compose bundle lists every key of its
  `x-tai-app-env` anchor; your own chart lists its pod-env keys). Those declared keys
  are refused upfront, named, rather than stored where they would shadow the deployment. A
  `TAI_SUPERVISED=k8s` or `compose` marker without the pinned list **refuses boot**,
  and so does a pinned list without one of those markers; `[]` is a legal empty list.
  Like the marker, the list is a deployment value no profile or env edit may carry.
  The bus URL is refused on **every** shape — the fleet census rides the bus, so
  recycling the bus out from under a live apply is intrinsically unobservable.

**Owned settings prefixes refuse unknown names.** The settings layer reads only the
variables a settings group declares, so a mistyped, renamed, or removed setting would
otherwise be ignored without a word. A settings group can declare its env prefix
**owned** — `ACCESS_CONTROL_`, `INTERACTIONS_`, and `CHANNELS_` are — and then every
variable under that prefix must name a registered setting. An unknown name (say
`ACCESS_CONTROL_ENABEL`) **refuses boot**, naming the variable and where it was read
(the process environment, the `.env` file, or the stored env), and an env write or a
profile that sets one is refused with a `400`. A config reload re-checks the stored env
it applies — so a name added to the store by hand is refused there, and the running
configuration keeps serving. Deleting an unknown name is always
allowed — an env write that empties it, or a profile that omits it — since that is the
fix. Inside a Kubernetes pod the container runtime injects link variables for every
Service in the namespace (`<NAME>_SERVICE_HOST`, `<NAME>_PORT`, …), and a Service named
like an owned prefix (`channels`, `access-control`) yields names under it: those are
not refused from the process environment where the Service's `<NAME>_SERVICE_HOST`
and `<NAME>_PORT` are both present; a lone one is refused like any unknown name. To
switch the link variables off, set `enableServiceLinks: false` on the pod.

**Stateful MCP sessions break on apply.** An apply builds a fresh serving generation
(an **epoch**) under the proposed env and swaps it in atomically; the old epoch is
retired. Retiring closes the old generation's FastMCP session manager, so the new
epoch serves a fresh session-id space with **no handoff**: a stateful MCP client's
session is terminated and it must re-initialize. In-flight HTTP requests and SSE
streams already admitted on the old epoch drain against it — only the MCP session
identity is severed, and a client treats it as a normal reconnect.

## The plugin model

Config providers are one member of a broader pattern. A **plugin** is any
separately-shipped package that registers through the `tai42_app` contract handle —
connectors, storage backends, config providers, [backends](/concepts/backends),
monitoring, and webhook verifiers. A plugin is loaded because the
[manifest](/concepts/manifest) names its module, and no plugin imports the
skeleton, which is what keeps the core provider-free and the ecosystem open-ended.

Change environment values and read the active mode from the CLI:

```bash theme={null}
tai config mode
tai config env set KEY=value
```

## Model providers

The platform's model layers are swappable the same way. Three selectors pick which
provider implementation backs each model type, and each defaults to a built-in
provider:

| Variable | Default | Selects the |
| - | - | - |
| `LLM_PROVIDER_LLM` | `openai` | chat-model provider |
| `LLM_PROVIDER_EMBEDDING` | `openai` | embedding-model provider |
| `LLM_PROVIDER_CLASSIFIER` | `typesafe` | [classifier](/concepts/classifiers)-model provider |

Each provider's own connection details ride the model's env namespace, resolved at use
time: `LLM_*` for the chat model, `EMBEDDING_*` for the embedding model, and
`CLASSIFIER_*` for the classifier (`CLASSIFIER_MODEL`, `CLASSIFIER_BASE_URL`,
`CLASSIFIER_API_KEY`, `CLASSIFIER_TIMEOUT`). An unset credential falls through to the
provider's own resolution and its loud error when none is available. A chat-model or
embedding-model setting the selected provider cannot carry (for example `LLM_TOP_K` with
`openai`, or `EMBEDDING_TIMEOUT` with `google`) is refused when the model is first built, with an
error naming the setting; no setting is silently dropped. The same setting given twice (for example
under its flat name and the provider's own name) is refused naming both. One case is caught only at
the first call: an OpenAI or xAI chat model with a built-in tool bound (a `gpt-6` model with any tool
bound) switches to the Responses call, and a setting only the Chat Completions call takes then fails
that call, before any request is sent. The full field table for every namespace is in the
[settings reference](/reference/settings#classifiersettings).

## Named databases

Every Postgres-backed component connects through a **named database** in one
central registry, not a private per-store connection namespace. A database
`<NAME>` is declared once under `TAI_DATABASE_<NAME>_PG_*`, and every component
bound to it — its migration chain, its boot-gate guard, and all of its stores —
resolves to that same connection, so a runner and its guard can never target
different databases. The registry ships one database, `default`, under
`TAI_DATABASE_DEFAULT_PG_*`; add more by declaring another name.

| Variable | Sets the database's |
| - | - |
| `TAI_DATABASE_<NAME>_PG_HOST` | Postgres host |
| `TAI_DATABASE_<NAME>_PG_PORT` | Postgres port |
| `TAI_DATABASE_<NAME>_PG_DB` | Postgres database |
| `TAI_DATABASE_<NAME>_PG_USER` | runtime role the stores connect as |
| `TAI_DATABASE_<NAME>_PG_PASSWORD` | password for the runtime role |

`<NAME>` is the registry name uppercased (`default` → `DEFAULT`). Pool sizes,
timeouts and the connect retry (`_PG_MIN_CONNECTIONS`, `_PG_MAX_CONNECTIONS`,
`_PG_CONNECT_TIMEOUT`, `_PG_STATEMENT_TIMEOUT_SECONDS`, `_PG_RETRY_ATTEMPTS`) tune
each database the same way; see [Connection timeouts and
retries](#connection-timeouts-and-retries).

**A database is configured when its password resolves to a non-empty value.** An
unconfigured database leaves every component bound to it cleanly
[**OFF**](#no-hidden-defaults-absent-means-off) — there is no baked-in `localhost`.
The host has no default either: a configured database with no
`TAI_DATABASE_<NAME>_PG_HOST` raises when its first connection is built.

### Admin identity

Migrations run as a DDL-privileged role, separate from the runtime role the stores
query with. Give a database its own migrator identity with:

| Variable | Sets the database's |
| - | - |
| `TAI_DATABASE_<NAME>_PG_ADMIN_USER` | migrator role |
| `TAI_DATABASE_<NAME>_PG_ADMIN_PASSWORD` | migrator password |

When the admin pair is unset, the migrator identity is that database's own runtime
user and password — one identity for both, the common single-role case. Setting
exactly one of the pair is rejected loudly at startup, naming both
`TAI_DATABASE_<NAME>_PG_ADMIN_USER` and `TAI_DATABASE_<NAME>_PG_ADMIN_PASSWORD` —
never a silent pairing of one admin field with the runtime one. Set the
admin pair only when DDL runs as a role distinct from day-to-day queries.

### Component bindings

Each migration **component** — the core (`skeleton`) and every installed plugin
that owns tables — binds to one named database:

| Variable | Default | Binds |
| - | - | - |
| `TAI_DB_BINDING_<COMPONENT_SLUG>` | `default` | the component to a registry database |

`<COMPONENT_SLUG>` is the component name uppercased with every character outside
`[A-Z0-9]` turned into `_`: the core `skeleton` reads `TAI_DB_BINDING_SKELETON`,
the accounts plugin `tai42-accounts-postgres` reads
`TAI_DB_BINDING_TAI42_ACCOUNTS_POSTGRES`. Left unset, a component binds to
`default`, so a single-database deployment sets only `TAI_DATABASE_DEFAULT_PG_*`
and every component shares it. Point a component at its own database by binding it
to another declared name.

## Default connection namespace

An optional **default namespace** supplies the one Redis connection every
Redis-backed feature falls back to, per field. Set the `TAI_DEFAULT_REDIS_*`
variables once and any feature that leaves its own Redis URL unset reads it from
there; a feature that sets its own URL always wins. Leaving them unset changes
nothing — each feature resolves exactly as it does without the namespace.

Only **connection-identity** fields fall back — the Redis URL and its connection
cap. Behavior knobs (socket and connect timeouts, retries, `decode_responses`)
never fall back and stay per-feature, so a blanket default can never reshape how
one feature talks to a backend it shares an address with.

| Variable | Seeds every feature's |
| - | - |
| `TAI_DEFAULT_REDIS_URL` | Redis URL |
| `TAI_DEFAULT_REDIS_MAX_CONNECTIONS` | Redis connection cap |

This is the full public surface — nothing outside this list falls back.

**Resolution order.** Each field resolves independently, taking the first source
that sets it:

1. the value written to the config store (manifest env / init);
2. the field's own environment variable;
3. the field's own `.env` entry;
4. a file secret for the field (`secrets_dir`);
5. the matching `TAI_DEFAULT_*` environment variable;
6. the matching `TAI_DEFAULT_*` `.env` entry;
7. the class-level default.

The default namespace sits below every store-specific source and above the built-in
class default, so a specific value always beats the default and the default always
beats the code-level fallback.

**Setting `TAI_DEFAULT_REDIS_URL` configures every Redis-gated feature — that reach
is the point.** A shared Redis URL is a deliberate act with fleet-wide effect: the
presence-gated features that run in-memory until a Redis URL appears — conversations,
hooks, sub-MCP, the [worker bus](/concepts/worker-bus), and their health and
readiness probes — all become Redis-backed at once, and the four channel correlation
stores (Slack, Telegram, Twilio, WhatsApp), each of which fails at first use when
unconfigured, become configured. Setting the default is how you turn those on
together; if that is not what you want, leave `TAI_DEFAULT_REDIS_URL` unset and give
each feature its own URL.

**Workers.** The arq, rq, and celery worker plugins take the same fallback:
`ARQ_REDIS_URL`, `ARQ_REDIS_MAX_CONNECTIONS`, `RQ_REDIS_URL`,
`RQ_REDIS_MAX_CONNECTIONS`, `CELERY_BROKER_URL`, `CELERY_RESULT_BACKEND`,
`CELERY_REDBEAT_REDIS_URL`, and `CELERY_REDBEAT_REDIS_MAX_CONNECTIONS` fall back to
`TAI_DEFAULT_REDIS_URL` / `TAI_DEFAULT_REDIS_MAX_CONNECTIONS` when unset — so an
unset celery broker runs on Redis rather than its AMQP class default once the
default namespace is set. Each worker plugin's Redis takes the shared connection
rows under its own prefix (`ARQ_`, `RQ_`, `CELERY_REDBEAT_`): `RETRY_ATTEMPTS`,
`RETRY_ON_TIMEOUT`, `SOCKET_TIMEOUT`, and `SOCKET_CONNECT_TIMEOUT`. They never fall
back. `ARQ_SOCKET_CONNECT_TIMEOUT` defaults to 1 second, and the arq worker's
startup connect is retried by `ARQ_RETRY_ATTEMPTS`.

**Startup visibility.** A store that fills any field from the default namespace logs
one INFO line at startup naming those fields — field names only, never values — so a
value arriving from `TAI_DEFAULT_*` rather than the store's own namespace is visible in
the boot log instead of silent.

**Prior art.** This is the shape of Rails' `database.yml` `default:` anchor —
per-key layered defaults that a specific environment overrides one key at a time — a
long-canonical pattern for connection config.

## No hidden defaults: absent means OFF

There is no baked-in `localhost`. A Postgres-backed feature is on only when the
[named database](#named-databases) its component binds to is configured; a
Redis-backed feature is on only when its own Redis URL — or the shared
`TAI_DEFAULT_REDIS_URL` — resolves. Absent either way, the feature is cleanly
**OFF**, never a silent connection to a local backend. Turning a feature on is
therefore a deliberate act: configure its bound database
(`TAI_DATABASE_<NAME>_PG_PASSWORD`), or give the Redis feature a URL.

Not every feature is OFF in this sense. Hooks, conversations, and sub-MCP
registrations run in memory. Access control, on by default, refuses to boot with no
identity provider and denies every keyed request without its Postgres or Redis. The
checkpoint store and the LLM store raise at first use, and so does starting a
connector OAuth flow without its Redis. [Infrastructure by
feature](/operate/infrastructure) lists every feature and what it does when its
service is missing.

### What OFF looks like

An OFF feature is a reported state, not an error — nothing 500s, nothing probes a
backend that is not there. Every surface answers honestly:

* **Reads answer empty.** A collection read returns `200` with an empty list; a read
  of a named entity returns `404`, byte-identical to a genuine miss.
* **Writes refuse with a named reason.** A mutation returns `501` with the JSON body
  `{"error": …, "code": "<feature>-not-configured"}` — the `code` is machine-readable
  so a caller can branch on it, and the message names the env var that turns the
  feature on.
* **Readiness skips it.** `/ready` omits an unconfigured feature entirely: an OFF
  feature never fails a readiness probe and is never probed.
* **Introspection labels it.** `GET /api/system/kinds` lists the feature with
  `state: "off"` and a detail naming the variable to set; the boot summary shows the
  same row.
* **Boot logs one line.** Startup emits a single `INFO` line per gated feature
  naming what is off and which env prefix turns it on — no traceback, no repetition.
* **Public doors stay uniform.** An unauthenticated door keeps answering with its own
  standard `404`, so an OFF feature opens no new oracle.

Rate limiting is the one loud case: with no Redis behind it, [every public
door](/concepts/access-control#flood-control-on-public-doors) passes through
**unthrottled** and boot emits one `WARNING` — never a boot refusal — naming
`TAI_RATE_LIMIT_REDIS_URL`.

### OFF behavior per feature

Each feature turns on the moment its connection resolves — a Redis feature from its
own variable or the shared `TAI_DEFAULT_REDIS_URL`, a Postgres feature from the
[named database](#named-databases) its component binds to. The table below is generated from the skeleton's
gated-feature registry — the same list `GET /api/system/kinds` reports — so it never
drifts from the code; the `Kinds row` column names the kind each feature reports and
the `off` state it carries when unconfigured.

| Feature | Enabling variable(s) | OFF behavior | Kinds row |
| - | - | - | - |
| Background tool runs | `TAI_TOOL_RUNS_REDIS_URL` | Run reads answer 200 empty (a single run reads 404); submit refuses 501 tool-runs-not-configured. | `tool_runs` reports `off` |
| Interactions + notifications | `INTERACTIONS_REDIS_URL` | The notification feed and stream refuse 501 interactions-not-configured (ask refuses as a tool error); feed reads answer 200 empty. | `interactions` reports `off` |
| Rate limiting | `TAI_RATE_LIMIT_REDIS_URL` | Pass-through — every public door (any route registered authed=False) is unthrottled; one boot WARNING. | `rate_limit` reports `off` |
| Marketplace store | `TAI_DATABASE_DEFAULT_PG_PASSWORD` | Installed and advisory reads answer 200 empty; the registry-proxy catalog is store-independent (502 against an unreachable registry); install and attribution writes refuse 501 marketplace-not-configured. | `marketplace_store` reports `off` |
| Tool-metadata overlay | `TAI_DATABASE_DEFAULT_PG_PASSWORD` | Folder and tag reads answer 200 empty; writes refuse 501 tool-meta-not-configured. | `tool_meta` reports `off` |
| Connectors store | `TAI_DATABASE_DEFAULT_PG_PASSWORD` | Connector endpoints answer OFF; writes refuse 501 connectors-not-configured. | `connectors` reports `off` |
| Versioning | `TAI_DATABASE_DEFAULT_PG_PASSWORD` | Preset and version reads answer 200 empty or 404; writes refuse 501 versioning-not-configured. | `versioning` reports `off` |
| Subject state records | `TAI_DATABASE_DEFAULT_PG_PASSWORD` | Every states read and write refuses 501 states-not-configured. | `states` reports `off` |

Access control is the one gate outside this table: with `ACCESS_CONTROL_ENABLE` off
(its Redis live context otherwise wired through `ACCESS_CONTROL_REDIS_URL` and its
policy store on the [named database](#named-databases) the core `skeleton` component
binds to), no gate runs on any request and the whole ecosystem is auth-free — its OFF
state surfaces through the `identity` kind row, not a gated-feature row.

### Local-dev recipe

For a laptop stack pointed at one local Redis and one local Postgres, configure the
`default` database and the shared Redis namespace once and leave every binding
unset — every component binds to `default` and every Redis feature falls back, so
they turn on together:

```bash theme={null}
TAI_DEFAULT_REDIS_URL=redis://localhost:6379/0
TAI_DATABASE_DEFAULT_PG_HOST=localhost
TAI_DATABASE_DEFAULT_PG_PORT=5432
TAI_DATABASE_DEFAULT_PG_DB=postgres
TAI_DATABASE_DEFAULT_PG_USER=postgres
TAI_DATABASE_DEFAULT_PG_PASSWORD=postgres
```

## Settings reference

Every setting below is read from the environment (or the managed `.env` store) at
use time. These are hand-maintained here — there is no generated reference for the
skeleton, toolbox, and agents settings, so this page is their canonical home.

### Core environment

| Variable | Default | What it does |
| - | - | - |
| `TAI_CONFIG_MODE` | `file` | Selects the config provider. `file` (default) reads from disk. Any other value names a config provider plugin, `tai42-config-<mode>` — `kubernetes` loads the Kubernetes config provider. A value that is not a well-formed mode name is **rejected loudly**. |
| `TAI_CONFIG_DIR_PATH` | `/app` | Directory the `file` provider anchors `.env`, `manifest.yml`, and templates under. |
| `TAI_MANIFEST_PATH` | — | Manifest path; also the default for `--manifest-path`. An empty value counts as unset. |
| `TAI_RUN_MODE` | unset | Unset/empty runs the normal multi-worker server; `debug` runs a single in-process server (ignoring `--workers`). Any other value is **rejected loudly**. |
| `TAI_LOG_LEVEL` | `INFO` | Root log level. A config reload re-applies it under `tai serve`. |
| `TAI_BODY_LIMIT_MAX_BODY_BYTES` | `10485760` (10 MiB) | App-wide request-body cap; oversized bodies get a `413`. |
| `SUB_MCP_REDIS_URL` | unset | Durable sub-MCP registration store. In-memory when unset (and `TAI_DEFAULT_REDIS_URL` is unset too). Under `tai serve --workers N` (`N > 1`), each worker refuses to boot while it is in-memory, and a reload or config write that would leave it in-memory is refused (see [Deploy](/operate/deploy#scale-workers)). |
| `HOOKS_REDIS_URL` | unset | Durable hooks registry. In-memory when unset (and `TAI_DEFAULT_REDIS_URL` is unset too). Under `tai serve --workers N` (`N > 1`), each worker refuses to boot while it is in-memory, and a reload or config write that would leave it in-memory is refused (see [Deploy](/operate/deploy#scale-workers)); so is a manifest that registers a task backend, at any worker count (see [Backends](/concepts/backends)). |

### Worker bus

The [worker bus](/concepts/worker-bus) is app-owned internal infrastructure — a
plain-Redis fan-out primitive, not a plugin. It is configured entirely through
these `TAI_BUS_*` variables; no manifest field selects a bus.

| Variable | Default | What it does |
| - | - | - |
| `TAI_BUS_REDIS_URL` | unset | Redis URL that enables the bus. Unset = bus off; the process runs on a no-op local bus (valid only for a single worker, `file` mode, no backend). **Required** for a multi-worker server, a registered backend, or `TAI_CONFIG_MODE=kubernetes` — the boot rules refuse those shapes without it. |
| `TAI_BUS_NAMESPACE` | `tai` | Prefixes the control channel, every reply channel, and every presence key. Redis pub/sub is server-global, so give each stack sharing one Redis a unique value. |
| `TAI_BUS_ACK_TIMEOUT` | `2.0` | Seconds the collector waits for the fast liveness acknowledgements before budgeting the rest of its wait toward the apply deadline. |
| `TAI_BUS_APPLY_TIMEOUT` | `90.0` | Seconds a mutation waits for every worker to finish applying — the report cut. Never below three drain budgets (refused at boot, on every reload and on every config change); the default budgets a worst-case reload plus the post-apply hooks. |
| `TAI_BUS_HEARTBEAT_TTL` | `15.0` | Presence-key TTL. A worker refreshes it at a third of this, so a frozen or killed worker leaves the census within one TTL. |

### Connector token encryption

Connector OAuth token blobs are encrypted at rest. Supply the key by env var name —
the value is never embedded in a manifest.

| Variable | What it does |
| - | - |
| `CONNECTORS_KEK` | Base64 32-byte AES-GCM key encrypting connector token blobs. Required once connectors store credentials. Blobs are always **encrypted** under this current key. |
| `CONNECTORS_KEK_PREVIOUS` | Comma-separated base64 32-byte previous KEK(s), retained only so decrypt can still open blobs written under a superseded key while a rotation converges. Set during a rotation, emptied once it completes. |

#### Rotating `CONNECTORS_KEK`

Rotating the current KEK on a live deployment does not brick stored tokens, because
decryption trial-decrypts a **key ring** — the current `CONNECTORS_KEK` first, then
each key in `CONNECTORS_KEK_PREVIOUS`. Encryption always uses the current key, so the
store converges onto the new key. To rotate:

1. **Carry the old key.** Set `CONNECTORS_KEK_PREVIOUS` to the current key's value and
   set `CONNECTORS_KEK` to the new key. Every stored blob still decrypts (via the ring),
   and every new/refreshed token is written under the new key.
2. **Converge the store.** Run `tai connectors reencrypt-tokens` (route
   `POST /api/connectors/tokens/reencrypt`). It scans every stored blob — expired
   sessions included — re-encrypts each one still under a previous key with the current
   key, and reports `{scanned, reencrypted, skipped, failed, failed_connection_ids,
   cas_retries}`. It is idempotent (a blob already under the current key is skipped) and
   compare-and-set safe (a concurrent token refresh is never clobbered). A blob no
   configured key can open is counted in `failed` and named — never silently dropped.
3. **Retire the old key.** Once the sweep reports `failed: 0`, clear
   `CONNECTORS_KEK_PREVIOUS`. The old key is no longer needed and its exposure window
   closes.

This is the controlled rotation path the key-material refusal points at (see
[Settings profiles](#settings-profiles) above, "Key material is refused, not
carried"): a KEK is rotated through these steps, never by carrying it in a settings
profile.

### Proxy pool (tai42-toolbox)

| Variable | Default | What it does |
| - | - | - |
| `PROXY_POOL` | empty | The operator's proxy-URL pool the `proxy` tool extension rotates over. |
| `PROXY_ALLOW_CALLER_URLS` | `false` | When `false`, a caller-supplied proxy URL not already in the pool is refused; set `true` to opt into caller-supplied URLs. |

### Timeouts and limits

Guardrails on downstream calls, concurrency, and payload sizes. All have safe
defaults; raise a timeout only when a legitimately longer operation needs it.

| Variable | Default | Bounds |
| - | - | - |
| `TAI_MCP_CALL_TIMEOUT_SECONDS` | `300` | Wall-clock budget for one downstream MCP tool call. |
| `TAI_MCP_SCHEMA_MAX_DEPTH` | `50` | Max JSON-schema nesting depth accepted when adapting an advertised MCP tool; a deeper schema skips that one tool. |
| `MCP_CLIENT_CONNECT_TIMEOUT_SECONDS` | `30` | Budget for an MCP client connect + init. |
| `MCP_CLIENT_KEEPALIVE_EXPIRY_SECONDS` | `30` | Seconds an idle connection to a remote MCP server is kept for reuse; must be positive. |
| `INTERACTIONS_BLOCKING_GRACE_SECONDS` | `5` | Outer bound a blocking `ask` waits past its own deadline. |
| `TAI_TOOL_RUNS_MAX_CONCURRENT_RUNS` | `32` | Per-worker cap on in-flight background tool runs; at capacity the submit door answers `503`. |
| `TAI_TOOL_RUNS_SHUTDOWN_DRAIN_SECONDS` | `10` | The drain budget, with three uses: how long shutdown waits for cancelled tool-run supervisors to write their terminal records, how long each drain of a reload's retire may take (in-flight requests, background runs, retired client pools), and the recycle orchestrator's per-step budget. `TAI_BUS_APPLY_TIMEOUT` stays at or above three of it. |
| `TAI_AGENTS_MAX_VOTERS` | `16` | Max voters a `voting_agent` invocation accepts. |
| `TAI_AGENTS_VOTER_CONCURRENCY` | `8` | Concurrent voters run per `voting_agent` invocation. |
| `TAI_AGENTS_EMBEDDING_DIMS_CACHE_SIZE` | `64` | Size of the retrieval agent's embedding-dimension cache. |
| `TAI_AGENTS_GRAPH_CACHE_SIZE` | `64` | How many compiled tools-agent graphs each event loop keeps for reuse (an LRU); a tool registration change or a settings reload makes the next run compile afresh. |
| `TEMPLATE_CACHE_MAX_SIZE` | `1024` | How many compiled templates each worker keeps; set it at or above the number of stored templates the deployment renders. |
| `TEMPLATE_CACHE_TTL` | `300` | Seconds a compiled template is kept; also bounds how long a template id known to be absent is remembered — a template created or edited directly in the storage backend, outside the platform, is seen within it. |
| `BATCH_DEFAULT_MAX_CONCURRENT` | `5` | Default concurrency for the `batch` tool extension. |
| `BATCH_MAX_BATCH_SIZE` | `100` | Max param sets a `batch` call accepts. |
| `TAI_SAMPLING_MAX_TOKENS_PER_CALL` | `32768` | Cap on tokens requested in one sampling call. |
| `TAI_SAMPLING_MAX_CALLS_PER_INVOCATION` | `20` | Cap on sampling calls per tool invocation. |
| `JQ_TIMEOUT_SECONDS` | `10` | Budget for one `jq` expression evaluation. |

#### Connection timeouts and retries

Postgres connection tuning is per [named database](#named-databases):
`TAI_DATABASE_<NAME>_PG_CONNECT_TIMEOUT` (default `10`),
`TAI_DATABASE_<NAME>_PG_STATEMENT_TIMEOUT_SECONDS` (default `60`) and
`TAI_DATABASE_<NAME>_PG_RETRY_ATTEMPTS` (default `0`) — for example
`TAI_DATABASE_DEFAULT_PG_CONNECT_TIMEOUT`. Each Redis-backed feature carries its own
tuning under its env prefix: `<PREFIX>SOCKET_TIMEOUT`,
`<PREFIX>SOCKET_CONNECT_TIMEOUT`, `<PREFIX>RETRY_ATTEMPTS` and
`<PREFIX>RETRY_ON_TIMEOUT` — for example `ACCESS_CONTROL_SOCKET_TIMEOUT`,
`TAI_TOOL_RUNS_RETRY_ATTEMPTS`.

* **Postgres.** `_PG_RETRY_ATTEMPTS` re-attempts **establishing** a connection when
  a pool is built: after a failed connect it waits and tries again, with an
  exponential backoff that starts at 16 ms and doubles to a 512 ms cap. A statement
  is never re-run. With `n` retries, building a pool waits at most
  `(n + 1) × _PG_CONNECT_TIMEOUT` plus the backoff.
* **Redis.** `<PREFIX>RETRY_ATTEMPTS` re-tries a failed connect **and the command**,
  writes included, with the same backoff. A subscription whose connection drops is
  reconnected and re-subscribed inside the same retry, so a drop shorter than the
  retry raises no error to the subscriber; a message published while it was
  disconnected is not delivered, as Redis pub/sub keeps no backlog. So each subscriber
  catches up after such a reconnect: the celery Redis result backend reads the stored
  state of every task it still awaits, so a result written meanwhile still arrives; the
  worker bus runs its resync (presence `resyncing`, the resync, then `ready`); and a turn
  waiting on a conversation thread retries the thread at once. A fleet operation's
  replies have no stored state, so when the publisher's reply subscription reconnects
  this way it logs a WARNING, keeps collecting the replies sent after the reconnect, and
  every worker left without a final reply carries the cause in its verdict
  (`reply collection transport error: the reply subscription reconnected …`). When the celery result
  backend's retry runs out, the wait raises the connection error, and the next wait, on
  any task, connects again, re-subscribes every task still awaited and reads their stored
  state. `<PREFIX>RETRY_ON_TIMEOUT` alone (with `RETRY_ATTEMPTS` at `0`) re-tries a
  timed-out command once, at once.
* **Every retry is logged.** Each retried failure logs one WARNING naming the
  connection — `Redis connection <SETTING> failed (attempt 1 of 3): …; retrying in …`
  or `Postgres connection '<pool>' failed (attempt 1 of 3): …` — and when the
  attempts run out the last error is raised; a Postgres one carries the note
  `Postgres connection '<pool>' failed after 3 attempt(s)`.
  With the defaults (`0`) a connection makes one attempt and fails at once.
* **A connection with its own connection string** takes its retry and timeouts from
  its own namespace, never from the base one: the model-provider store and
  checkpointer (`LLM_PROVIDER_STORE_*` / `LLM_PROVIDER_CHECKPOINT_*`:
  `RETRY_ATTEMPTS`, `RETRY_ON_TIMEOUT`, `SOCKET_TIMEOUT`, `SOCKET_CONNECT_TIMEOUT`,
  `PG_RETRY_ATTEMPTS`), the celery Redis result backend (`CELERY_RESULT_BACKEND_*`)
  and the celery Redis broker (`CELERY_BROKER_*`, read and write sides alike). With
  them unset, that connection makes one attempt. The celery broker never retries a
  read kombu polls: a worker's task and fanout reads, and a control command's reply
  read in any process. A drop there raises at once: a worker's consumer restart
  reconnects, and a control call fails with the connection error, so a retry of that
  call reconnects.

> [!NOTE]
>
> A specific config provider's setup — for example which secret store and config
> source it reads — lives in that provider package's own repository, reachable
> from the [Plugins section](/plugins). The platform documents the provider
> contract, not any one provider.

See the [CLI reference](/reference/cli/index) for `tai config`.


# Connectors
Source: https://docs.tai42.ai/concepts/connectors

OAuth connections to outside apps.

A connector is an OAuth connection to an outside app. It binds a running server to
a third party — Google, Atlassian, and others — and manages the token exchange and
storage so a tool can call an authenticated API without ever handling raw
credentials.

## The provider-agnostic engine

The connector engine is provider-agnostic. The domain and wire models and the
provider ABCs live in the contract; the skeleton owns the runtime — the OAuth
flow, the token store, the resolver, and the stdio glue.

A provider is one **descriptor** — a `ProviderDescriptor` — declaring the
provider's id, its OAuth or no-auth mode, the env var names that hold its client
credentials, its sub-services and their scopes and MCP endpoints, and an `icon_url`
brand mark. The `icon_url` must be an `https://` URL (the same rule the plugin
descriptor's `icon` follows), so the catalog serves it verbatim with no bundled
asset to host. See the [ProviderDescriptor
reference](/reference/python-sdk/contract-connectors) for the full schema.

Providers come from the server [manifest](/concepts/manifest)'s `connectors`
list. A [marketplace](/concepts/marketplace) install of a connector patches one
descriptor into that list; you can also add one by hand. The server registers
each listed descriptor at boot and on every reload — there is no import
side-effect and no code to install, so a whole OAuth integration is just a
manifest entry.

## Tokens resolved at call time

A managed connection is referenced from the manifest by its provider and
sub-service; the actual credential is resolved at call time, per outbound request.
The resolver serves a healthy, still-fresh token on the hot path without locking,
and only takes a lock to refresh a stale one — so replicas racing an expired token
converge on one refresh.

The resolved credential is injected on the right channel for the transport: an
`Authorization: Bearer` header for HTTP, or the `_meta` token field for a stdio
MCP server. A connection can also be no-auth-with-config, in which case configured
values are injected as headers or environment instead of a token.

## Where tokens live

The token store keeps tokens in Redis as a cache and Postgres as the source of
truth. It comes up **only when its database is configured** — the [named
database](/concepts/config-and-secrets#named-databases) the core `skeleton`
component binds to, on with a non-empty `TAI_DATABASE_<NAME>_PG_PASSWORD` — the
same presence gate every other database-backed feature uses. That gate is what
turns connectors on for a deployment; absent it, connectors are off and startup
never opens Postgres for them. With the database configured and none reachable,
startup fails loudly.

The **provider catalog is not loaded from the database**. The server registers
each descriptor in the [manifest](/concepts/manifest)'s `connectors` list through
its `register_connector` seam at boot and on every reload, so listing and
resolving providers reads the in-memory registry and never touches Postgres. Only
the token store, above, uses the database.

## Connection health

A connection carries a health state, so a token that has stopped refreshing or a
connection that needs re-authorising surfaces as a clear, typed condition rather
than a silent failure at call time. Reconnect-required and refresh-failing states
raise their own errors. A successful reconnect re-probes, on every worker, the
connection's entries that its lapsed credential had knocked out, so their tools
return at once rather than at the background re-probe's next pass.

## Engine settings

The engine's own settings apply to every connector, not to any one provider. A
provider adds only its own client credentials (the `CONNECTORS_<PROVIDER>_*` env
var names its descriptor declares); these `CONNECTORS_*` keys are shared:

| Variable | Default | Effect |
| - | - | - |
| `CONNECTORS_KEK` | unset | Base64 32-byte key encrypting stored tokens (AES-GCM). Required — the engine raises when it needs to encrypt or decrypt and this is missing or malformed. |
| `CONNECTORS_STATE_HMAC_KEY` | unset | Base64 key of at least 32 bytes signing the OAuth `state`. Required. |
| `CONNECTORS_REDIRECT_URI_ALLOWLIST` | empty | Comma-separated origins allowed to receive the callback. Empty rejects every connect flow — there is no implicit fallback. |
| `CONNECTORS_OAUTH_BRIDGE_URL` | unset | Shared bridge origin, when the callback does not live on this deployment. It must also appear in the allowlist or every connect flow fails closed. |
| `CONNECTORS_MAX_SESSION_TTL` | 180 days | Longest a stored connection stays valid — an inactivity cap, reset on every successful use or refresh. |

The `CONNECTORS_KEK` and `CONNECTORS_STATE_HMAC_KEY` are key material: they are kept
out of logs and are refused inside a settings profile. The origin a provider registers
with must appear in `CONNECTORS_REDIRECT_URI_ALLOWLIST`, and it must be https for
anything but a local host.

## Managing connections

Drive the OAuth lifecycle from the CLI:

```bash theme={null}
tai connectors providers      # list the registered providers
tai connectors connections    # list live connections
tai connectors connect <provider>
tai connectors reconnect <id>
tai connectors disconnect <id>
```

> [!NOTE]
>
> The platform documents connectors at the platform level. A specific provider's
> setup — its scopes, redirect URIs, and environment — lives in that connector's
> own repository, reachable from the [Plugins section](/plugins).

See the [connect-an-OAuth-provider guide](/guides/connect-an-oauth-provider) for
the end-to-end flow and the [HTTP API reference](/reference/api/index) for the
connector routes.


# Deep agents
Source: https://docs.tai42.ai/concepts/deep-agents

Durable, code-executing agents on the ordinary Agent contract.

A deep agent is a multi-step agent that runs durable, code-executing work — it
plans, composes other agents, and keeps a working filesystem across steps. It is
built on the same authoring surface as any [agent](/concepts/agents) — the `Agent`
contract — so there is no separate framework to learn. "Deep agents" is a concept
word for that behavior, **not** a platform module: the depth is durable,
code-executing behavior, not a new kind of object.

There is no separate "deep agent" module or framework behind them: a deep agent is
registered and run exactly like any other agent, against the same `Agent` ABC.

## Sub-agents

The contract carries a neutral sub-agent descriptor. An agent declares the
sub-agents it can call, and the agents runtime constructs the live, typed
sub-agent from that descriptor at run time. This is how a top-level agent
delegates part of its work to a more specialised one and assembles a multi-step
result.

Because sub-agents are ordinary agents, everything on the [agents](/concepts/agents)
page applies to them: the same registration, the same typed
[stream events](/concepts/agents), and the same run tool.

## The ready-made agents

The platform ships ready-made deep agents you enable from the
[manifest](/concepts/manifest), rather than authoring them yourself. They are part
of the batteries-included default set — usable platform content — so their usage
lives in-site: see [the agents plugin](/plugins/tai42/agents) for the per-agent
reference and [the guide](/guides/use-the-ready-made-agents) for enabling and
running each one.

## Durable execution via the sandbox

A deep agent reaches the same [sandbox](/concepts/sandbox) seam every
code-executing agent does, and there are two patterns for how it does so. In the
**session-driving** pattern the agent drives an external code runtime inside a
sandbox session over the `SandboxSession` contract. In the
**durable-scratch-backend** pattern the agent's working filesystem *is* a sandbox
backend over that same contract, so its scratch files persist and reap under the
operator's durability settings. Either way the sandbox is a hard prerequisite: an
agent whose scratch backend is the sandbox fails loudly when no
[sandbox provider](/operate/sandbox) is installed, so installing one is not an
optional add-on.

## Crash-resume

A long detached run can be re-driven from its durable checkpoint plus its
persistent workspace after a process recycle — when the operator turns
crash-resume **on**. Re-drive is at-least-once. With crash-resume off, a recycled
run accepts the risk and surfaces loudly. It is a setting, not a default.

## Authored deep agents

A deep agent's configuration can itself be saved and versioned as an authored
agent — a [preset](/concepts/presets) that bakes the agent's preset-bakeable
fields and rides the [versioning spine](/concepts/versioning-spine). That lets you evolve a
multi-step agent's wiring over time without breaking the callers that run it.

See the [author-an-agent guide](/guides/author-an-agent) for the authoring path,
the [use-the-ready-made-agents guide](/guides/use-the-ready-made-agents) for worked
runs, [operate/sandbox](/operate/sandbox) for installing a provider, and the
[Python SDK reference](/reference/python-sdk/index) for the sub-agent descriptor
and the `Agent` ABC.


# Hooks
Source: https://docs.tai42.ai/concepts/hooks

Logic that runs at points in the request lifecycle.

A hook binds an inbound event topic to a tool. When an external system delivers an
event on a topic, the hooks manager keeps the event as one run per hook registered
for that topic, then runs each hook whose condition matches the payload, with its
bound tool in the background. A run that fails before its hook acts, for a reason
that can pass, is retried; a run that fails after, or for a reason no retry can change
(such as a condition that cannot evaluate), is held as failed for an operator
([Kept and retried](#kept-and-retried)).

This page explains the model. To register one, use the Studio's
[Hooks screen](/studio/hooks) or follow
[Fire a tool from a webhook](/guides/fire-a-tool-from-a-webhook).

## The dispatch model

A hook is a small record: a topic, the tool to run, the static keyword arguments to
pass it, an optional condition, and the jqs that shape and drive the fired run.
Registration is keyed by topic, so one topic can drive several hooks and the manager
dispatches to all of them: an event on a topic becomes one **hook run** per hook,
kept in the hooks store until it finishes:

```json theme={null}
{
  "topic": "event_created",
  "tool": "notify_team",
  "tool_kwargs": { "channel": "ops" }
}
```

The condition is what makes dispatch selective — a hook fires only when its
condition matches the event payload, so one topic can route different events to
different tools.

A hook is also a **parkable door**: beside `condition` it carries the [door
contract](/concepts/asking-the-caller#the-door-contract) — `start_expr` builds the
fired tool's kwargs from the payload (the static `tool_kwargs` win on a key clash;
absent, the tool fires with `tool_kwargs` only), and `cancel_expr` / `resume_expr` /
`extras_expr` cancel, resume, or hand extras to the run's [parked
interactions](/concepts/asking-the-caller). A hook fire has no receiver, so a resumed
run's terminal [waits on the subject](/concepts/asking-the-caller#waiting-outcomes) for
its next owner to take.

`condition` and the door-contract jqs are jq, and they say so in the schema: each
carries the [`x-tai42-expression` annotation](/reference/api/index#expression-fields),
which names the input document and what the result is consumed as, and binds the run's
parked interactions as [`$parked`](/concepts/jq-variables#doors). An editor reads that
annotation and offers the [visual jq editor](/studio/jq-editor) on the field
without being told which fields are expressions.

## Naming a hook and topic

A hook's `topic` is dispatched as one path segment of the public webhook URL
(`/universal_webhook/{topic}`), and its `name` addresses the hook on every
management and delete door. Both must be a single URL-safe path segment: match
`^[a-z0-9][a-z0-9_-]*$` — begin with a lowercase letter or digit, then lowercase
letters, digits, underscores, and hyphens only. No dots, slashes, uppercase, or
whitespace — a `/` or a stray character would mint a record no delivery could
route to and no door could address. The value is never sanitized: a violation is
rejected at registration with a `400`, its message naming the offending field and
the pattern.

A hook that carries a state binding has it checked and its templates attached at
registration; a refused binding stores no hook. A binding naming an undeclared state is a
`404`, an occupied attach path a `409`, and a states-store failure a `500` — see [saving a
binding](/concepts/states#saving-a-binding).

## The ingress door

External systems deliver events to the public `POST /universal_webhook/{topic}`
door. The payload parser accepts any content type. Before the door answers, the
event is kept as one hook run per hook on the topic, so a `200`
`{"status": "accepted"}` means the event is kept: its runs then run, and are
retried, in the background, and the ingress never waits for the tools to finish.
When the hooks store refuses to keep the runs, the door answers a `500` and keeps
nothing, so the sender's own retry delivers the event again. The body is
`{"error": "accept failed"}`, or `{"error": "webhook verification error"}` on a
topic whose verifier claims each delivery id; that claim is not kept either, so
the retry is not refused as already seen.

A multipart form whose parts include a file is answered `400`
(`{"status": "rejected", ...}`), here and on a trigger link, and nothing is kept:
a kept hook run carries text fields only.

> [!NOTE]
>
> The in-memory hooks manager keeps its runs in the serving process only: they are
> lost when that process stops, and a sibling worker never sees them. A deployment
> that relies on kept runs uses the Redis-backed manager.

> [!WARNING]
>
> `/universal_webhook/{topic}` is the most exposed door on a server. A topic with no
> [verifier](/concepts/triggers-and-webhooks) binding is open by design; bind a
> webhook verifier to a topic to authenticate every inbound event over its raw body
> before it is parsed and dispatched. The [public-door flood
> limiter](/concepts/access-control#flood-control-on-public-doors) throttles the door
> regardless.

## Kept and retried

Every event the ingress accepts is kept, one run per hook on the topic. A run lives in
the hooks store until it finishes, or until an operator retries or discards it once it
is held as failed.

**When the hook acts.** The hook acts when its visit cancels a parked interaction,
commits a resume or take claim, or starts the tool. Before that point every failure is
retried automatically, with backoff (`HOOKS_RUN_RETRY_BASE_SECONDS`, doubled per
attempt, capped at `HOOKS_RUN_RETRY_CAP_SECONDS`), up to `HOOKS_RUN_MAX_ATTEMPTS`
attempts in all. That covers the condition, the state-context render, the `$parked`
read, the door contract, the visit's own checks and the wait for pending saves, when
they fail for a reason that can pass, such as a store out of reach. The failure kinds
no retry can change (bad input, unauthorized, not found, conflict, cancelled) fail the
run at once.

A condition that raises when jq evaluates it over the run's payload is bad input: the
same payload raises again on every attempt. The run fails after one attempt, is kept in
the failed set and reported like any failed run, and its tool never runs. Fix the
condition by registering the hook again under the same name, then retry the run; the
retry reads the hook as it is registered now.

**After the hook acts.** Once the hook acts, the platform adds no automatic attempts.
A tool that wants its own failures retried declares a `ToolRetryPolicy`, and exactly
that policy runs. Any failure after that point holds the run as failed.

**Interrupted runs.** A run can be interrupted by a crash or a lost lease, by a
graceful shutdown, or by a config apply that retires the serving generation while the
hook's tool runs.

* A run interrupted after it started a tool replays **that start alone**, with the same
  input, the same extras and the same `tai42/idempotency_key` extra
  (`TOOL_EXTRA_IDEMPOTENCY_KEY`), and only when the tool declares
  `TOOL_META_CRASH_RESUME`. Otherwise it is held as failed.
* Any other run interrupted after its hook acted is held as failed.
* A shutdown first gives the hook runs in flight `HOOKS_RUN_SHUTDOWN_GRACE_SECONDS` to
  finish, before anything else drains their tools.
* A tool that raises its own `CancelledError` fails its run (kind `cancelled`). Only a
  shutdown or a config apply that drains the tool counts as an interruption.

**A stopped claim is never re-run blindly.** A run stopped while its hook was making a
resume or take claim first checks, on its next attempt, whether the entry is still
open. Still open means the claim did not commit, and the run is retried automatically.
No longer open means the entry was resolved, and the platform cannot tell whether this
run's claim or another door (an answer, an expiry, another caller, the retention sweep,
a TTL) resolved it. The run is then held as failed, and its error says so and lists the
ids. Check the interaction, then discard the run, or retry it as a fresh run whose
checks and door contract decide again.

**Every attempt counts.** Every attempt counts toward `HOOKS_RUN_MAX_ATTEMPTS`, an
interrupted one and a replayed start included, so a run that keeps meeting restarts or
config applies ends in the failed set instead of repeating.

A resumed run's own redelivery belongs to the interactions reaper (see [sync and
async](/concepts/interactions#sync-and-async)). A taken outcome is consumed when it is
taken.

**Across restarts and replicas.** A running attempt holds a lease
(`HOOKS_RUN_LEASE_SECONDS`, renewed while it runs). Every serving process sweeps the
store every `HOOKS_RUN_SWEEP_SECONDS`: it runs the runs that are due, and takes over the
runs whose lease lapsed, so a run of a process that crashed is picked up by a restarted
process or by another replica.

**How many run at once.** `HOOKS_MAX_WORKERS` bounds the hook runs in flight per
process. A config apply that changes it applies from the next run admitted; it never
cancels a run in flight. Runs begun before a config apply keep their shutdown grace.

**A failed run.** A run held as failed stays in the store until an operator retries or
discards it. The platform logs it at ERROR, sends an operator notification, fires the
`hooks_run_failed` [platform event](#platform-events), and counts it in the
`tai42_hook_runs_*` metrics. The run list shows, per run, `acted` (what the hook had
done: `""`, `cancel`, `resume`, `take` or `start`), `acted_ids` (the interactions it
acted on) and `claim_intent` (a claim it was making when it stopped).

```bash theme={null}
tai hooks runs list --status failed
tai hooks runs retry <id>
tai hooks runs discard <id> --yes
```

A retry replays the start of a run that had started its tool, and otherwise runs the
hook again. A run whose hook committed a resume or a take cannot be retried, only
discarded, and the refusal says why. The same doors are `GET /api/hook-runs`,
`POST /api/hook-runs/{id}/retry` and `DELETE /api/hook-runs/{id}`.

The settings are listed under [HooksSettings](/reference/settings#hookssettings).

## Targeting a state subject

A hook may carry an optional **subject** so a [state](/concepts/states) write during
the fire is keyed and attributed to the hook. The subject names a
conversation-target scope, a subject `kind`, and a `key_expr` — a jq expression
evaluated over the event payload at fire, which must yield a non-empty string:

```json theme={null}
{
  "topic": "event_created",
  "tool": "record_status",
  "subject": {
    "target_kind": "agent",
    "target_name": "A-42",
    "kind": "person",
    "key_expr": {"content": ".actor"}
  }
}
```

The fire runs with this subject as its ambient state context: a state tool the
hook calls resolves the subject from it, and the write is recorded under door
`hook` with the hook's execution key as the actor. A `key_expr` that yields nothing
fails the fire loudly, like any hook error. Leaving `subject` unset leaves the fire
with no ambient state context, so a state tool it calls must carry an explicit
subject. The Studio's [Hooks screen](/studio/hooks) surfaces the subject as an
optional group on the register form.

## Platform events

The platform also fires topics of its own, for a background event an operator should hear
about. A hook registered on such a topic fires exactly as it does for an external event, so a
deployment routes the alert wherever it wants — a chat-line, a pager, a ticket. Among them:

| Topic | Fired when | Payload |
| - | - | - |
| `interactions_ask_expired_unanswered` | an ask expires with no answer ([Interactions](/concepts/interactions)) | `interaction_id`, `group_id`, `channel`, `recipient`, `expired_at` |
| `interactions_ask_expiry_abandoned` | a parked ask's keys aged out past its retention horizon before the expiry reaper reached it, so no `on_expiry` action ran and no door terminal was committed ([Interactions](/concepts/interactions#deadlines-and-retention)) | `interaction_id`, `expiry_at` |
| `states_outbox_save_failed` | a pending state save fails and holds its subjects ([States](/concepts/states#pending-saves)) | `save_id`, `run_id`, `phase` (`records` or `calls`), `subject_keys`, `error_kind`, `error` |
| `hooks_run_failed` | a hook run is held as failed ([Kept and retried](#kept-and-retried)) | `run_id`, `topic`, `hook`, `attempts`, `acted`, `acted_ids`, `error_kind`, `error` |

A failure to fire a platform event is logged at WARNING and never stops the work that raised
it; the event's cause is already logged on its own.

## Managing hooks live

Hooks are managed at run time, with no restart. The manager comes in an in-memory
and a Redis-backed form (`HOOKS_REDIS_URL`, or `TAI_DEFAULT_REDIS_URL`); the in-memory
form is per-process, so under `tai serve` with more than one worker each worker
refuses to boot on the in-memory form (a reload or config write that would leave it
in-memory is refused too), and a config that registers a task
[backend](/concepts/backends) is refused over the in-memory form at any worker count (the backend process matches the events it raises
against its own registry, which would hold none of the hooks registered through the
server). The authed management doors (`GET`/`POST`/`DELETE`
`/api/hooks`) are a thin skin over it — the same manager the hook-management
[operations](/concepts/live-operations) drive. Register and remove hooks from the
CLI:

```bash theme={null}
tai hooks list
tai hooks register --params '{"name":"notify-ops","topic":"event_created","tool":"notify_team","tool_kwargs":{"channel":"ops"}}'
tai hooks delete <name>
```

`register` takes the whole hook record — topic, tool, kwargs, and an optional
condition — as one `--params` JSON object; its full option set is on the command
itself:

```bash examples/hooks/register_hook.sh theme={null}
# Register a hook by passing the whole HookParams record as one --params JSON
# object (name, topic, tool, tool_kwargs, an optional condition, and the door-contract
# jqs start_expr/cancel_expr/resume_expr/extras_expr).
tai hooks register --help
```

Setting or removing a topic's verifier binding is a separate authed door
(`PUT`/`DELETE /api/hooks/topics/{topic}/verifier`). The kept runs have their own
authed doors — `GET /api/hook-runs`, `POST /api/hook-runs/{id}/retry` and
`DELETE /api/hook-runs/{id}`, driven by `tai hooks runs list|retry|discard` (see
[Kept and retried](#kept-and-retried)).

See the [fire-a-tool-from-a-webhook guide](/guides/fire-a-tool-from-a-webhook) for
the binding-and-condition workflow, [triggers and webhook
verifiers](/concepts/triggers-and-webhooks) for authenticating the ingress, and
the [HTTP API reference](/reference/api/index) for the hook routes.


# Concepts
Source: https://docs.tai42.ai/concepts/index

The core subsystems of the platform, one page per pillar.

The core subsystems of the platform, one page per pillar. Start with the layering
and the manifest — they explain how a server is built and what it loads — then read
the pillars you need.

## Foundations

> **[The layering](/concepts/layering)**
>
> Contract, kit, cli, skeleton, and the Studio.

> **[The manifest](/concepts/manifest)**
>
> The single file a server loads at startup.

> **[Tools and extensions](/concepts/tools-and-extensions)**
>
> Atoms of work and the clip-on powers over them.

> **[Presets](/concepts/presets)**
>
> Versioned, named wraps of a tool.

## Agents

> **[Agents](/concepts/agents)**
>
> LLM-driven capabilities and how they are authored.

> **[Deep agents](/concepts/deep-agents)**
>
> Multi-step agents and the ready-made set.

> **[Client conversations](/concepts/client-conversations)**
>
> The conversation an MCP client drives.

## Around the tool

> **[Interactions](/concepts/interactions)**
>
> Human-in-the-loop, in-client and external.

> **[Connectors](/concepts/connectors)**
>
> OAuth connections to outside apps.

> **[Hooks](/concepts/hooks)**
>
> Bind an inbound event topic to a tool.

> **[Triggers and webhooks](/concepts/triggers-and-webhooks)**
>
> Firing tools from outside events.

> **[Storage and resources](/concepts/storage-and-resources)**
>
> The ResourceManager and stored content.

> **[Backends](/concepts/backends)**
>
> Where tools run: background, scheduled, distributed.

## Platform surfaces

> **[Access control](/concepts/access-control)**
>
> The jq-policy request-auth gate.

> **[Accounts](/concepts/accounts)**
>
> Human accounts, sessions, and login flows.

> **[User types and permissions](/concepts/permissions)**
>
> The identity types and what each may reach.

> **[Owned keys](/concepts/owned-keys)**
>
> Delegation as a capped sub-identity.

> **[Config and secrets](/concepts/config-and-secrets)**
>
> Swappable config and secret providers.

> **[Transports](/concepts/transports)**
>
> HTTP, SSE, STDIO, and the UDS path.

> **[Private tool sets](/concepts/private-tool-sets)**
>
> Scoped sub-MCP servers.

> **[The MCP-citizen surface](/concepts/mcp-citizen-surface)**
>
> MCP-native features and the FastMCP escape hatch.

> **[The versioning spine](/concepts/versioning-spine)**
>
> One versioned-store primitive, many kinds.

> **[Live operations](/concepts/live-operations)**
>
> Operate a server without a restart.

> **[The worker bus](/concepts/worker-bus)**
>
> How a config change reaches every worker.

> **[The marketplace](/concepts/marketplace)**
>
> The plugin index: listings, items, versions, advisories.


# Interactions
Source: https://docs.tai42.ai/concepts/interactions

Human-in-the-loop, in-client and external.

An interaction pauses a run to ask a person a question and blocks until they
answer or the question times out. The `ask` tool is the core capability: it
suspends the caller mid-run, records the question, and wakes the caller with the
answer.

This page explains the model — asking a **person**. An `ask` can also be addressed
to the **run that called this one** (`to="caller"`), which parks and hands the
question up rather than out to a human; that variant is [asking the
caller](/concepts/asking-the-caller). To turn interactions on and answer one, follow
[Use interactions](/guides/use-interactions).

## The loop

```mermaid theme={null}
flowchart TD
    A["a tool or agent calls ask"] --> B["record the question,<br/>block the caller"]
    B --> C["human sees it on the SSE stream"]
    C --> D["human answers"]
    D --> E["record the answer,<br/>wake the blocked caller<br/>with answer, reply_to, params"]
    E --> F["the run resumes"]
```

`ask` is the engine-agnostic author surface behind the contract's `Ask`
protocol. Loading it is manifest-driven: opt in the interactions tool module and
the interactions HTTP router, exactly like any other capability.

## Sync and async

A question also declares a **wait discipline**, `mode`:

* **`sync`** (the default) blocks the caller. The loop above is the sync loop: the
  caller waits on the answer or the `timeout`, then `{answer, reply_to, params}`
  returns — the typed answer, the message the answering reply quoted, and the channel's
  params (or the call raises).

  The answer comes back unchanged, with two fields beside it. **`reply_to`** is the message
  the answering reply quoted, `{message_id, status, text}` — the same shape a conversation
  turn reads ([replies to an earlier
  message](/reference/conversation-bridge#replies-to-an-earlier-message)) — kept apart from
  the answer and never merged into its text; it is `null` when the reply quoted nothing or did
  not come over a channel. **`params`** are the channel's own string entries about the
  answering tap or reply (for example the `media_*` entries of a photo reply), passed
  through with no platform meaning; `null` when there are none, and on expiry. Each channel's
  [plugin page](/plugins) names its entries.
* **`async`** parks the caller. `ask` records — and, over a channel, delivers —
  the question exactly as sync does, but returns a **suspension sentinel**
  immediately instead of blocking. A later answer, or the question's expiry, resumes
  the run out of band.

An async park always carries a deadline: `expiry_at`, a timezone-aware moment. It is
**required** for `async` — a park with no deadline could never expire, so the ask
raises without it — and **mutually exclusive** with a sync `timeout`, which bounds
the same wait the other way. `expiry_at` is valid only with `mode="async"`.

A parked question is answered **out of band** — through the ordinary authenticated
answer door or the channel callback, exactly as a sync question, never inline. When a
human answers, the run resumes on its own: a stored continuation runs under the
**asker's** identity (never the answerer's), exactly once. It receives `answer`,
`reply_to` and `params`, the same values a synchronous asker reads.

What a **lapsed** `expiry_at` does is the park's **`on_expiry`** policy:

* **`kill`** (the default) tears the whole run chain down. The parked run — and every
  run linked above it — is failed, and a door that started it with a receiver is
  delivered a single failure. An unanswered deadline ends the work rather than
  resuming it.
* **`resume`** resumes the continuation with a reserved *interaction expired* marker
  in place of an answer, so the run takes its **expiry branch** rather than a real
  answer. Choose it when the run has an expiry path to run. The marker arrives as
  `answer`, with `reply_to` and `params` `null`.

Either way the expiry is stated once as an `interactions_ask_expired_unanswered`
platform event a deployment can [hook](/concepts/hooks) on.

Async requires the run to be resumable: it must be raised where a resuming driver
and a bound execution identity are in scope, or it raises loudly rather than
silently blocking.

Async also requires a **durable, cross-worker checkpointer** — `redis` or
`postgres`. The continuation may resume on a different worker than the one that
parked the run, so its checkpoint must live in shared storage; an in-memory,
sqlite, or checkpointing-disabled setup cannot cross that boundary, and an async
park on one raises loudly.

### Withdrawing a parked ask

A parked ask can also be taken down on purpose: by the cancel door
(`POST /api/interactions/{id}/cancel`, `tai interactions cancel`), by a door contract's
`cancel_expr` or the `cancel_parked` tool, or by erasing the conversation thread, route or
person it belongs to. Each one tears the whole run chain down, exactly as an
`on_expiry="kill"` lapse does.

Every takedown, a lapse included, frees the channel's hold on the person at once. A channel
that keeps one open question per person releases that person, so the next ask to them goes
out straight away instead of being refused until the old one lapses. The question already
sent stays on the medium. A late reply to it finds no open question and is treated like any
[late reply](#delivering-to-a-channel): with a channel route bound it enters the conversation
as an ordinary message (a late WhatsApp form submit arrives as a message carrying the form's
values).

What differs is the terminal the door that started the run receives. A run ends in one of
three terminals: `succeeded` (its result is delivered), `failed` (any non-success; a
conversation route sends the failing target's reply when the failure carries one, else the
route's `reply_texts.error`, else the built-in line) and `withdrawn` (taken down on purpose;
nothing is delivered). A deliberate takedown delivers `withdrawn`, so a conversation route
sends nothing and announces nothing: the person is told nothing. Among takedowns, only an
`on_expiry="kill"` lapse delivers `failed`.

A door receives its terminal through the delivery address it binds before the run starts
(`set_park_completion`, a tool plus an opaque context). The platform fires that tool with
the bound context merged with the fire's own keys: `thread_id`, `result`, `completion_id`,
`status` and, only on a `failed` fire whose failure carries a target reply, `reply`. A bound
context that carries any of those five keys is refused when the address is bound, so a
context can never stand in for the fire's own data. An address tool for a door that shows
text to a person accepts an optional `reply` and shows it in place of its fixed failure line.

### Parking several at once

A run can raise more than one async `ask` before it suspends — a parallel
fan-out that parks on all of them together. Each ask is independent: it carries its
own `expiry_at`, and its answer or expiry can arrive in any order, from any surface,
on any worker. The run buffers each resolution durably and resumes **once**, when
the **last** ask resolves — never once per answer, and never part-way on a partial
set. A mix of real answers and `on_expiry="resume"` expiries resolves the same way: an
expired ask contributes the reserved *interaction expired* marker to its own branch
while its siblings contribute their answers, and the single resume carries them all
together. An `on_expiry="kill"` ask that lapses is different — it tears the whole
fan-out down rather than resuming it. A lone async ask is the one-ask case of this
same path.

### A flow or an agent parks

The resuming driver is engine-agnostic: a flow and an agent run are both drivers.
An agent whose tool raises an async `ask` parks the whole agent run and resumes
it on the answer or expiry exactly as a flow resumes — the same stored continuation,
the same asker identity, the same once-only resume. Parking an agent run needs the
same durable, cross-worker checkpointer as any park (`redis` or `postgres`); an agent
run on an in-memory or sqlite checkpointer refuses the async ask loudly rather than
parking a run nothing could resume. It also needs the agents package's own durable
park index — a configured Redis that reverses a parked interaction id back to the
run that parked it, independent of the checkpoint provider; a park-capable run with
no park index configured refuses the async ask loudly before any state is written.

Parallel subagents each park in one step: when several nested subagents raise an
async `ask` together, all their parks collapse into one suspend, and the run
resumes **once** when the last of them resolves — answers and expiries arriving in
any order, from any surface, on any worker, exactly as parallel asks resolve on a
flow.

When a parked agent was reached over a chat channel, its resumed final reply is
posted back into the originating conversation thread, so the late answer lands where
the person is talking. A parked **tool or flow** turn reached over that same channel
delivers its resumed reply back the same way — mapped through the route's reply
mapping — so a conversation target of any kind lands its late answer in the same
thread.

### Deadlines and retention

An async ask's `expiry_at` is the **deadline** — the moment the question stops
mattering, which fires its [`on_expiry`](#sync-and-async) policy. The **checkpoint retention** is a
different clock: the paused run's checkpoint lives in the checkpointer's own store for the
[waiting retention](/operate/checkpoints#retention-two-horizons) after its last write (7 days by
default), after which it is reclaimed. The two must agree: an async ask whose `expiry_at` lies
beyond that horizon would lose its paused graph before the answer or expiry ever arrives — so
the park is refused **loudly when it suspends**, naming the interaction, its `expiry_at`, and
the horizon it exceeded.

The park's own records keep one more clock, the **retention horizon**. Every key an async park
writes (its state, its group's stream and count, its run and thread indexes and its callback
ticket) lives until `expiry_at` plus `INTERACTIONS_IDLE_TTL_SECONDS` (24 hours by default).
The expiry reaper runs every `INTERACTIONS_EXPIRY_REAPER_INTERVAL_SECONDS` (30 seconds by
default) and resolves a lapsed park whenever it reaches it inside that horizon, so a late or
stalled reaper still applies `on_expiry`. Both answer doors stay open for the same window: the
callback ticket lives as long as the park, and an answer is taken for as long as the park is
still pending. A park the reaper reaches only after its horizon has passed can no longer be
resolved: it is logged at ERROR and stated once as an `interactions_ask_expiry_abandoned`
[platform event](/concepts/hooks#platform-events) carrying `interaction_id` and `expiry_at`.
No `on_expiry` action runs and nothing is delivered to the door.

An agent run holds its asks to a tighter deadline. The platform may still deliver an ask's
answer or expiry up to that retention horizon after the deadline, so an
[agent](/plugins/tai42/agents) parks only an ask whose deadline leaves the whole horizon
before its checkpoint's retention runs out (with the defaults, within 6 days). An ask past
that point is refused loudly before anything is parked, and a resume that finds the
checkpoint gone ends the run as a failed terminal.

## Answer formats

A question declares one of five answer formats. Four are answered on an
authenticated **in-client** surface — the caller waits while a person responds
through the answer door:

* **`text`** — free text.
* **`confirm`** — a yes/no acknowledgement.
* **`select`** — a choice from options.
* **`form`** — a typed payload validated against a declared schema. Answered
  in-client through the answer door, or — over a [channel](#delivering-to-a-channel)
  that supports forms — rendered as that channel's own form surface (see the
  [channel capability matrix](/concepts/notifications#channel-capability-matrix) for
  what each renders).

The fifth format is **`external`**: the human acts on an outside surface — signs a
document, approves a request, confirms an action — and the external system delivers the answer
back through a public callback door. The asking tool blocks exactly as it does for
any other format; only the delivery channel differs.

### Prefilling, per-send options and pages

A `form` ask can refine its schema per send with two optional keys, both generic to
every consumer and channel:

* **`data`** — a per-send overlay on the schema. `data.values` prefills top-level
  properties with known answers (keyed by property name), so the person confirms or
  edits rather than typing from scratch. `data.options` supplies per-send choice
  lists (keyed by property name) that replace a string property's `enum` for this one
  send — each option a `value` (what the answer carries), an optional `label` (the
  text shown in its place), and an optional `description` (a second line drawn with
  the label) — so a variant needs no republished form.
* **`pages`** — an ordered list of pages, each a `title` and the property names it
  groups, splitting a longer form into steps. Every top-level property appears
  exactly once across the pages; an absent `pages` is a single page.

A **field** can carry a second line of its own: the standard JSON-Schema `description`
on the property draws as a hint under the field's `title` label, so a short label keeps
the rest of the text (a time, a price, a note) on a second line. A field `description`
and an option `description` are optional and carry content, so a surface whose control
has no native second-line slot draws the text in the nearest text affordance by that
surface's documented rule — never silently dropped. The platform sets no length bound;
each channel enforces its own medium's limit in its own code.

Both are validated against the schema before the ask is sent: an unknown property, a
value that fails its property's schema, options on a non-string property, or a page
that misses, repeats, or names an unknown field raises loudly, naming the field. A
channel that cannot honor per-send data refuses at delivery — naming the field —
rather than dropping it silently.

```json theme={null}
{
  "schema": {
    "type": "object",
    "properties": {
      "date": {"type": "string", "format": "date"},
      "count": {"type": "integer", "description": "How many to include"},
      "notes": {"type": "string"}
    },
    "required": ["date", "count"]
  },
  "data": {
    "values": {"count": 2},
    "options": {
      "date": [
        {"value": "a", "label": "Option A", "description": "Morning slot"},
        {"value": "b", "label": "Option B", "description": "Evening slot"}
      ]
    }
  },
  "pages": [
    {"title": "Basics", "fields": ["date", "count"]},
    {"title": "Extras", "fields": ["notes"]}
  ]
}
```

The prefilled `count` arrives filled in under a `count` field that shows its
`description` as a hint, `date` offers the two labelled choices this send provides —
each with its own second line — and the form reads as two steps. The same `data` and
`pages` carry to every surface that renders the form.

### Multiple choice and radio

Besides a scalar, a form property may be an **array of strings** — a
**multiple-choice** field whose answer is the list of chosen values. Declare it as an
`array` whose `items` are a `string`, optionally with an `items.enum` (or a per-send
`data.options` list) for the choices:

```json theme={null}
{
  "type": "object",
  "properties": {
    "regions": {
      "type": "array",
      "items": {"type": "string", "enum": ["emea", "amer", "apac"]}
    }
  }
}
```

A single-choice field stays a `string` with an `enum`. How a choice list renders is
the surface's call, decided by the option count against one shared, documented
threshold — `RADIO_OPTION_THRESHOLD` (**5**): a list **at or under** the threshold
renders as a radio group (for a single-choice `string`+`enum`) or a checkbox group
(for an array-of-strings), a longer one as a dropdown or multi-select. Every surface
draws the same short list the same way. A [per-send `data.options`](#prefilling-per-send-options-and-pages)
list replaces the choices for one send, for an array-of-strings field exactly as for
a scalar `enum`.

### Date constraints

A date property — a `string` with `format` `date` or `date-time` — may carry
platform date-constraint keys, validated when the form is built and **enforced on the
answer at every door**:

* **`minDate`** / **`maxDate`** — inclusive `YYYY-MM-DD` bounds.
* **`unavailableDates`** — a list of excluded days, each a `YYYY-MM-DD` date or a
  lowercase weekday name (`monday` … `sunday`) excluding that weekday.

```json theme={null}
{"type": "string", "format": "date", "minDate": "2026-01-01", "maxDate": "2026-12-31", "unavailableDates": ["2026-07-04", "saturday", "sunday"]}
```

A **date range** is **two ordinary date fields**, never one combined value. The
**end** field names its start field in `rangeStart` and carries the span bounds
`minDays` / `maxDays` (inclusive day counts); each field's answer stays the plain date
string its type declares:

```json theme={null}
{
  "type": "object",
  "properties": {
    "start": {"type": "string", "format": "date"},
    "end":   {"type": "string", "format": "date", "rangeStart": "start", "minDays": 1, "maxDays": 14}
  }
}
```

Each end of a range of two `date` fields may have a **time**: a `string` with `format`
`time` that names its end in **`timeOf`**. The time stays its own field and its own
`HH:MM` or `HH:MM:SS` answer; nothing is recombined.

```json theme={null}
{
  "type": "object",
  "properties": {
    "start":      {"type": "string", "format": "date"},
    "end":        {"type": "string", "format": "date", "rangeStart": "start"},
    "start_time": {"type": "string", "format": "time", "timeOf": "start"},
    "end_time":   {"type": "string", "format": "time", "timeOf": "end"}
  }
}
```

The answer door enforces the ordering (`end` on or after `start`) and the inclusive
span from the two submitted values — identically whether a surface drew them as two
inputs or as one native range control mapped to the two fields, so nothing is ever
recombined:

* Two `date` ends are ordered by date, and the span counts the days. When both fall on
  the same date and each has a time, they are then ordered by those times: an end time
  before the start time is refused on the **end time's** field (*The end time must be on
  or after the start time*). When either time is absent, the dates alone decide.
* A mixed pair (one `date` end and one `date-time` end, either way round) is ordered by
  each value's written date, and its span counts the days.
* Two `date-time` ends are ordered by their full instants, so an end on the same day but
  before the start is refused. Both instants are read in the START's offset, and the span
  is the inclusive count of calendar days between them in that offset, so a range in
  order always spans at least one day. Each answer stays the string the end user wrote,
  so with different offsets the END's written date may be earlier than the START's while
  the range is in order.

The web widget, Studio and the callback page check the order inside the form as well,
except for two `date-time` ends: the widget and Studio leave those to the answer door, and
the callback page skips them (their end input carries `data-range-instant`), so the
answer door alone checks them.

Wherever a form is drawn or read back, each time is listed **right after its date**,
whatever order the schema declares them in: on the page, in a range control (each time
under its date), and in a review readback. In WhatsApp, where the two dates merge into one
range picker, both times come after the picker: the start time, then the end time. A time
and its date sit on the same page.

A nonsensical constraint — a date key on a non-date property, `maxDate`
before `minDate`, a `rangeStart` naming an undeclared or non-date property, `minDays`
above `maxDays`, a span key on a field with no `rangeStart`, a `timeOf` on a field that
is not `format: time`, a `timeOf` naming something other than a `date` end of a range,
a `timeOf` on a range whose other end is `date-time` (a time without an offset cannot be
ordered against it), a second time for the same date, a time whose `visibleWhen`
differs from its date's, or a time on another page than its date — is refused loudly
when the form is built, naming the property. This holds on every door that carries a
form: an ask over a channel, an ask answered in the inbox, a `notify_user` form and a
conversation form part. Each key renders as the matching native control where a
surface has one (see the [capability table](#form-capabilities-per-channel)); where a
surface cannot bound its date control, the bound is still enforced on submit.

### Conditional fields

A property may carry a **`visibleWhen`** predicate making its visibility depend on
another field's value — `{"field": <other property>, "equals"|"in"|"notEmpty": …}`,
exactly one operator per predicate:

```json theme={null}
{
  "type": "object",
  "properties": {
    "has_account": {"type": "boolean"},
    "account_id":  {"type": "string", "visibleWhen": {"field": "has_account", "equals": true}}
  }
}
```

`equals` is visible when the named field equals the value, `in` when it is one of a
non-empty list, `notEmpty` (which must be `true`) when it is present and not an empty
string / list / object. The named `field` must be another declared property.

**The effective-answer rule.** Whether a field is part of the answer is decided by its
predicate **evaluated on the submitted values**, at the single answer facet, so it
holds on **every** answer door — authenticated, callback, channel-forwarded, and the
expiry path alike. A field hidden by that evaluation is **removed from the answer**
the consumer receives: it is not required, not validated, and a value submitted for it
— filled before it was hidden, or filled on a surface that degraded to drawing every
field — is **dropped, never an error**.

### Display elements and a review page

A page may carry ordered **display blocks** beside its input fields — a `heading`, a
`body`, or an `image` — through its optional `display` list, and may be a terminal
**review** page:

```json theme={null}
{
  "title": "Summary",
  "fields": [],
  "kind": "review",
  "display": [
    {"kind": "heading", "text": "Review your entry"},
    {"kind": "image", "src": "https://cdn.example.com/logo.png", "alt": "Acme"},
    {"kind": "body", "slot": "total"}
  ]
}
```

A `heading`/`body` block carries `text`; an `image` block carries a `src` and an
optional `alt` (the text a surface that cannot draw the image shows instead). A block
is either **static** (its `text`/`src` given here) or declares a **`slot`** — a name a
[reaction](#forms-that-react-while-open)'s `display` update fills while the form is
open (a computed total is a display slot, nothing special). A slot name is unique
across the form.

A page is an **input** page (`kind: "input"`, the default) or a **review** page
(`kind: "review"`): a terminal summary step that carries **no input fields** (an empty
`fields`). A surface renders a review page as a readback of the entered values
alongside its display blocks and the confirm/submit control.

## Media on a question

A question can carry optional **media** — images and links shown WITH it in the
inbox, above the answer controls. Media is **display-only**: the person still
answers through the question's `answer_format`, and the media never becomes part
of the answer. It is orthogonal to the answer format — valid with every one — and
renders with the question both while it is pending and after it is answered.

![The Interactions inbox showing a question with its attached images and links rendered above the answer controls.](https://mintcdn.com/tai42/svAMgtenosCg9O5X/images/studio/scoped-interactions-light.png?fit=max\&auto=format\&n=svAMgtenosCg9O5X\&q=85\&s=e0f5efe77c5571dbff006a97e850c483)

The Interactions inbox rendering a question's media — images and links shown above the answer controls.

Each item is a `MediaItem` — a `kind`, a `url`, an optional `caption`, and (for a
document) an optional `filename`:

```json theme={null}
{"kind": "image",    "url": "https://cdn.example.com/chart.png",  "caption": "The weekly chart"}
{"kind": "document", "url": "https://cdn.example.com/report.pdf", "filename": "report.pdf", "caption": "Q3 report"}
{"kind": "video",    "url": "https://cdn.example.com/clip.mp4",   "caption": "The walkthrough"}
{"kind": "audio",    "url": "https://cdn.example.com/note.mp3"}
{"kind": "link",     "url": "https://docs.example.com/reports",   "caption": "Open the full report"}
```

* **`kind`** — one of five. The **file kinds** `image`, `document`, `video`, and
  `audio` carry a fetchable body and render as the matching bubble (an `image`
  inline, the others as the matching file element); a `link` renders as a labelled
  anchor the person clicks through. In the Studio inbox a `document` is a download
  link labelled by its `filename` or `caption`, and `audio`/`video` play in a native
  player only from the deployment's own `/api/interactions/media/<id>` reference (a
  player has no referrer control); an item the inbox cannot show reads
  "Media item N could not be shown." in its place, and the question stays answerable.
* **`url`** — the source. A file kind is an absolute **`https`** URL or a same-origin
  **`/api/interactions/media/<id>`** reference to media the deployment serves by id;
  `image` **additionally** admits an inline `data:image/*` URI (that inline form is
  image-only — a `data:` URI on any other kind is refused). A `link` is an absolute
  **`http(s)`** URL. Remote file media is https-only: the inbox content-security policy
  admits `https:`, `data:`, and same-origin sources but not `http:`, so an `http:`
  file source would be a record that could never render — it is rejected up front, not
  silently dropped. Anchors are not governed by that policy, so an `http:` link stays
  valid.
* **`caption`** — optional accessibility text: an image's alt text, a file's label, or
  a link's display label.
* **`filename`** — optional suggested display name for a **`document`** download; it is
  meaningful only on a `document` item and is refused on any other kind.

### Caps

Media and the question text are bounded by the contract. These are wire-contract
properties — they bound the ask (and notify) **request** a tool submits, not a
replay — not operator settings:

| Cap | Value | What it bounds |
| - | - | - |
| `QUESTION_MAX_CHARS` | 8192 | one question's text |
| `MEDIA_MAX_ITEMS` | 50 | items on one ask or notify — a loose abuse guard |
| `MEDIA_URL_MAX_CHARS` | 8192 | one `http(s)`/`https` URL |
| `MEDIA_DATA_URI_MAX_CHARS` | 524288 (512 KiB) | one submitted `data:image/*` URI |
| `MEDIA_CAPTION_MAX_CHARS` | 1000 | one caption |
| `MEDIA_TOTAL_URI_CHARS` | 1048576 (1 MiB) | the summed url text across all items |

`MEDIA_MAX_ITEMS` is a loose platform abuse guard on the item count, not a
per-channel limit: WhatsApp, for one, delivers each image as its own message, so
the guard — not a native per-message envelope — bounds how many items an ask or
notify may carry. The byte caps
bound the submitted request, not a replay: an accepted `data:image/*` image is
stored by reference — the record keeps a same-origin `/api/interactions/media/<id>`
url and the bytes are served from that route for the question's lifetime. The
pending inbox is read as a paged list through `GET /api/interactions`, and the SSE
stream is tail-only, so no historical backlog is replayed whole on (re)connect — a
reconnecting client resumes recent events by [`Last-Event-ID`](#reading-the-stream)
instead.

### Limits

* **Display-only.** Media rides the question, never the answer. The person's
  reply carries no media.
* **Forwarded to channels that render it.** A question always persists to the
  inbox, where its media renders. When the same question is also delivered to a
  [channel](#delivering-to-a-channel), its media rides the delivery too — the channel
  renders it alongside the question. It is a pure enhancement, not structure: a
  channel that renders only text simply ignores it (no capability flag, never a
  refused send). The channel copy carries an **absolute** served url, so a stored
  `data:image/*` image reaches the medium from the deployment's own
  `/api/interactions/media/<id>` route rather than as inline bytes — a channel ask
  that submits a `data:` image therefore needs the deployment's public base URL
  configured, exactly as a media notification does.
* **Privacy.** A remote `https` image is fetched directly by the reader's
  browser, which discloses the reader's IP (and request timing) to the image
  host. An agent that must avoid that discloses nothing by submitting a
  `data:image/*` URI — the deployment stores it by reference and serves the bytes
  from its own `/api/interactions/media/<id>` route, so the reader's browser only
  ever contacts the deployment.
* **Validated before anything is stored.** Invalid media — an empty list, a
  non-`http(s)` link, an image url that is neither `https`, a `data:image/*` URI,
  nor a same-origin `/api/interactions/media/<id>` reference, an over-cap url,
  data URI, caption, or total, a blank caption, or more than `MEDIA_MAX_ITEMS`
  items — raises loudly when the question is built, before any state is written.

## External questions

An `external` question requires a `link`. A string link is a template carrying the
literal `{callback_url}` placeholder; a callable link receives the callback URL,
builds the external resource, and returns its final URL. The returned answer is the
payload the callback delivered — a JSON POST body, or the query params of a
GET confirm flow — validated against the question's schema when one is declared.

`ask_external` packages this as a [transformer extension](/concepts/tools-and-extensions):
it wraps a tool that builds an external resource and drives the whole flow. The
wrapped tool takes a `callback_url` parameter and returns the URL to visit.

A `verifier` binds a registered [webhook verifier](/concepts/triggers-and-webhooks#webhook-verifiers)
to the callback so a signed server-to-server answer is authenticated before it is
recorded. It is the same `{"verifier": <name>, "config": {...}}` binding a hook topic
uses (the contract's `TopicVerifierBinding`), whether it is passed to `ask(verifier=...)`
or bound as `ask_external`'s author config:

```yaml theme={null}
extensions:
  create_resource:
    - - name: ask_external
        config:
          verifier:
            verifier: shared_secret
            config: {header: X-Signature-Token, secret_env: CALLBACK_SECRET}
```

A binding of any other shape is refused when the ask is made (`ValueError`) and when
the manifest loads (`ask_external`'s config); a stored binding that does not validate
answers every callback `500` and records nothing.

### The callback URL and its pin

Every callback URL the platform mints has one shape:
`{INTERACTIONS_PUBLIC_BASE_URL}/api/interactions/callback/{ticket}`. A plugin reads the
prefix from `tai42_app.interactions.callback_url_prefix()` (`None` when no public base is
configured). Every component that POSTs to a stored callback URL — the platform's own
inbound answer ladder, the web channel's answer and reaction doors, a tool that answers a
question it opened — first pins it with `tai42_kit.interactions.pin_callback_url(url,
prefix=...)`: only the exact minted shape passes (same scheme, host and effective port,
no userinfo, query or fragment, one ticket segment), and anything else raises
`CallbackUrlRefusedError` with a reason (`host_mismatch`, `path_mismatch`,
`malformed_url`) and the target host — never the URL, which carries the ticket. A
deployment that changes `INTERACTIONS_PUBLIC_BASE_URL` while questions are open refuses
their callbacks loudly.

## Delivering to a channel

By default a pending question surfaces on the authenticated stream — the Studio
inbox. Passing `channel="<name>"` to `ask` hands delivery to a registered
**channel plugin** (Telegram, Slack, SMS/WhatsApp) instead: the question mints a
public callback ticket exactly like an `external` ask, the plugin pushes it to
the person on that medium, and the reply comes back through the same callback
door. The asking tool blocks exactly as before — only the delivery leg changes.
An unknown channel name, or a delivery failure, raises loudly before the run
would wait on an answer that can never arrive.

A channel's `deliver` returns the address the question went to and its message ids, and
the question is recorded in the participant's conversation thread as a [send
record](/reference/conversation-bridge#send-records) when the channel has a bridge route for
that identity. The record ends `failed` when every attempt was refused, `outcome_unknown`
when an attempt timed out and none succeeded, with a WARNING that the participant may have
the question twice when an attempt timed out before one succeeded, and `delivered` once
the participant's reply over the channel lands. For a `sensitive` question the record keeps
that the reply came, when, and its message id, never the reply's body, so the transcript,
the record views, message search and a quote of that reply show no body. An operator's
answer through the answer door, or a caller resume, leaves the record's delivery state as it
was and shows no reply on it.

The platform never hands a channel a question whose deadline has already passed: the
delivery fails with a non-retryable error ("already timed out … nothing was sent"), the
question is pruned and the `interactions_delivery_failed` event fires — checked again after
every retry backoff, so a deadline that passes mid-retry is refused before the next send.

A reply that arrives after the question is already gone or expired is not lost:
with a channel route bound it enters the conversation as an ordinary inbound
message; with no bound route it is logged and dropped.

A channel may render a `select` question **natively** — WhatsApp, for instance,
shows the options as tappable reply buttons or a list, and past the medium's
option cap it falls back to a numbered text prompt. How the options render is the
channel's choice; the **answer contract is unchanged**. However the person
responds — tapping a control or typing — the answer is the option **text**,
exactly as a typed reply would deliver it, and it validates against the
question's options the same way.

A `text` question may also carry **`options`** as *suggested replies* — a tappable
shortlist offered alongside the free-text box. Unlike a `select`'s options they
constrain nothing (a text answer still accepts any string): a tap simply submits the
option's own text as the free-text answer. A channel that advertises interactive
support renders them however it chooses; one that cannot falls back to the plain
prompt.

A `form` question rides a channel only when that channel advertises
`supports_form_delivery`; a form sent to a channel without the flag raises loudly,
naming it, before anything is sent. The person fills it on that channel's own form
surface — the [channel capability matrix](/concepts/notifications#channel-capability-matrix)
records what each renders — and the typed answer returns through the callback door,
validated against the schema exactly as the in-client door validates it.

Because a channel form is answered on the server-rendered callback page, its
`schema` must fall in a renderable **subset**, checked when the question is asked —
before anything is stored. The root is `{"type": "object"}` with a non-empty
`properties` map; every property is a scalar (`string`, `boolean`, `integer`, or
`number`) **or an array whose `items` are strings** (a
[multiple-choice](#multiple-choice-and-radio) field); an `enum` — a non-empty list of
strings — is allowed on a `string` property or on an array's string `items`; and
`required`, when present, names only declared properties. A property that is neither a
scalar nor an array-of-strings — a nested object, an array of non-strings, a bare
`anyOf`/`oneOf`/`$ref`, a missing type — is refused with a `ValueError` naming the
property, while an extra constraint keyword alongside a renderable `type` is not
rendered but is enforced when the answer is validated. A date property may also carry
the [date-constraint keys](#date-constraints), and any property a
[`visibleWhen`](#conditional-fields) predicate; both are validated here and enforced
on the answer. A form on the default inbox surface keeps full JSON-schema freedom; the
subset binds only a channel-delivered form.

A `string` property may also carry a **`format`** of `date`, `time`, `date-time` or
`email`; any other `format` value, or a `format` on a non-string property, is refused,
naming the property. The answer door validates the value's shape: `date` is `YYYY-MM-DD` (a
real calendar date), `time` is `HH:MM` or `HH:MM:SS`, `date-time` is an RFC 3339
timestamp (a mandatory `Z` or `±HH:MM` offset), and `email` is one `@`, a dot in the
domain, and no whitespace (`^[^@\s]+@[^@\s]+\.[^@\s]+$`). A `format` alongside an `enum` is
allowed — the enum's choice control is rendered and the format is still validated on
the answer.

Each surface renders a `format` string as its medium's native control where one
exists, and as a plain text input where none does. Where the shape is checked is set out in
[Shapes are caught inside the form](#shapes-are-caught-inside-the-form); the answer door
always checks it again:

| `format` | WhatsApp | Slack | Callback page¹ | Web widget | Studio |
| - | - | - | - | - | - |
| `date` | calendar picker (returns `YYYY-MM-DD`) | `datepicker` | `<input type="date">` | `<input type="date">` | browser date input |
| `time` | text, checked inside the form | `timepicker` (`HH:mm`, 24-hour, no seconds) | text, checked on the page | text (validated at the door) | browser time input |
| `date-time` | text, checked inside the form | text (validated at the door) | text, checked on the page | text, checked inside the form | text, checked inside the form |
| `email` | email keyboard, checked at the data endpoint | `email_text_input` | `<input type="email">`, checked on the page | `<input type="email">`, checked inside the form | email input, checked inside the form |

¹ The callback page renders the Telegram web-app button, the external-link door, and
the web channel — each answers on the same server-rendered form page. A `date` prefill
must be `YYYY-MM-DD` and a `time` prefill `HH:MM`; a prefill a native control cannot
display (a `time` carrying seconds on Slack, say) is refused when the form is built.

### Shapes are caught inside the form

A field's declared shape (`required`, `pattern`, `format`, `minLength`/`maxLength`,
`minimum`/`maximum`, `minItems`/`maxItems`, the date constraints) is checked inside the form
wherever the surface can, so the person sees a plain sentence under the field before the
submit leaves it. Whatever a surface does not check itself, the answer door checks on submit,
and it checks every shape again in any case: it refuses a broken answer with the platform's
sentence for the first failing field, naming that field. Where each shape is checked:

| Shape | WhatsApp | Slack | Callback page¹ | Web widget / Studio |
| - | - | - | - | - |
| `required` | the control | the modal | the browser | the form |
| `pattern` | the control on a text or numeric keyboard, else the data endpoint | the door | the page | the form |
| `format: email` | the data endpoint | the door (drawn as `email_text_input`) | the page | the form |
| `format: time` / `date-time` | the control and the data endpoint | the door (`time` drawn as `timepicker`) | the page | `date-time` the form, `time` the door |
| `minLength` / `maxLength` | the control's limits (a text area's minimum: the data endpoint) | the input's own limits | the page | the form |
| `minimum` / `maximum` | the data endpoint | drawn as `number_input` `min_value`/`max_value` | the page | the form |
| exclusive bounds, `multipleOf` | the data endpoint | the door | the door | the door |
| `minItems` / `maxItems` | the selection limits | the door | the door | the form |
| date constraints | the calendar picker (a range's order and span, when the range is drawn as two fields, and a range's time order: the data endpoint) | the door | the page | the form |

The sentence the person reads depends on the surface:

* **WhatsApp, the callback page, the web widget and Studio** show the sentence the sender set
  as `wording.form.fields[<name>].invalid`: their own words, in the end user's language, used
  for every shape error on that field but never for a missing required value. A missing
  required value reads the sender's `wording.form.fields[<name>].required` instead, on
  WhatsApp (drawn by the data endpoint, for a value carried from an earlier screen; the
  control on the current screen checks its own), the callback page, the web widget and
  Studio (both through the Studio SDK); without it each surface shows its own word, and
  where the browser's or the vendor's own native check runs, that check's own words show.
  Without the `invalid` sentence,
  WhatsApp shows its own short word for the broken shape, the callback page shows the
  platform's sentence naming the bound (*Enter at least 10 characters*), and the web widget
  and Studio, which check the form with the Studio SDK, show its own words (*must be at least
  10 character(s)*); an unavailable day on the callback page shows the page's own line.
  WhatsApp caps the `invalid` and `required` sentences at 30 characters on a text field or
  text area and 80 on a calendar or choice control; a longer one is refused at deliver,
  naming the field. WhatsApp's line above a refused form is the sender's
  `wording.form.error_line` when set, else its own *Label: sentence* list.
* **Slack** pins the door's sentence for the failing field under it (*Enter a valid email
  address*), wrapped by the sender's `wording.answer.rejected` when set.

![A callback form with an Email address field holding alice@ and the sentence Enter a valid email address under it.](https://mintcdn.com/tai42/pM3vF4Kt7boveAKM/images/callback-page/form-field-error.png?fit=max\&auto=format\&n=pM3vF4Kt7boveAKM\&q=85\&s=457984e4a4a113acd2d987182ebde857)

The callback page showing the platform's sentence under a field whose value is not an email address.

A number's `minimum`/`maximum` (or their exclusive forms) that no value lies within (for an
`integer`, no whole number, as in `minimum: 1.2`, `maximum: 1.8`), a `minLength` above
`maxLength` and a `minItems` above `maxItems` are refused when the form is asked, naming the
property, on every channel and for a form answered in the in-app inbox.

A form whose schema breaks the JSON Schema rules is refused when the form is asked, naming the
property and where in it the value sits, on every channel and for a form answered in the
in-app inbox. That covers a bound that is not a number, a negative `minLength`, a `pattern`
or `patternProperties` key that does not compile (one too large or too deeply nested to
compile included), `patternProperties` keys that cannot be combined into the one expression
`additionalProperties` checks, and a number that is not finite (`Infinity`, `NaN`) anywhere in
the schema. A `free` or `external` ask's schema is held to the same rules. A `$schema` that is
not a URI string is refused, at the root or on any subschema; a subschema naming another
dialect is held to that dialect's rules.

References follow the same rules. A `$ref` or `$dynamicRef` must resolve to a valid subschema
inside the schema itself (`#`, a `#/…` pointer, a `#anchor`, or an absolute reference under the
schema's own root `$id`), or into a JSON Schema meta-schema by its URI. A reference naming any
other schema is refused, since no schema is ever fetched, and so is a cycle of references that
never descends into the answer. A `#/…` pointer indexes an array only with `0` or a whole
number without a leading zero (`-1`, `+1` and `01` are refused). A pydantic model's
`$defs`/`$ref` resolve this way.

A schema is one resource. A `$id` below the root, or an anchor name declared twice, is refused.
So is a root `$id` (or draft-04 `id`) that is the URI of a JSON Schema meta-schema, with or
without a trailing `#`, since the schema would take that meta-schema's place; this includes a
meta-schema pasted as it is. When the root has a `$id`, a `$dynamicAnchor` below the root is
refused if a reference into a meta-schema would jump back into the schema at it: its name is
one the part of the meta-schema the reference leads to (or any part that part refers to) uses
for its own `$dynamicRef` (`meta` in the draft 2020-12 meta-schema and its core, applicator,
content and unevaluated vocabularies), or the name the reference itself points at, such as
`https://json-schema.org/draft/2020-12/schema#meta`. A reference to a part that never refers
to the name is accepted: draft-07, the 2020-12 validation vocabulary, or a pointer such as
`https://json-schema.org/draft/2020-12/meta/core#/$defs/anchorString`.

A form may not name a top-level property or a display slot `__proto__`: JavaScript reads that
name as an object's prototype, so a form drawn in a browser cannot keep it. Such a form is
refused wherever it enters: when it is asked (on every channel and for a form answered in the
in-app inbox), when it is sent in a notification, and when it is carried in a conversation
answer part. It is the only reserved name; `constructor`, `toString` and other names are
allowed.

When you don't need to **wait** for the answer, send the form as a
[notification](/concepts/notifications#ask-less-forms) instead: `notify_user` with a
`schema` delivers the same schema-rendered form and returns immediately — no ticket,
no expiry, no validation loop — and the submission enters the conversation as an
ordinary message from the person. The ask is for answers the caller blocks on; the
ask-less form is for submissions that are welcome whenever they arrive.

### For channel authors

A channel plugin reads the platform's rules from their owners instead of copying them:

* **Callback-link formats** — `tai42_contract.interactions.CALLBACK_LINK_FORMATS`
  (`confirm`, `external`) are completed by opening the callback link alone; every other
  format expects a reply the channel correlates.
* **Reaction events** — a channel routes a form reaction to `tai42_app.interactions.react`
  as a typed `FormReactionEvent`: `FieldChangedEvent(field=...)`,
  `PageAdvancedEvent(page=...)` or `SubmittedEvent()`. The HTTP react doors take the same
  event as JSON; an unknown `kind` or an extra key is refused `400`.
* **Form vocabulary** — `tai42_kit.interactions` exports the `visibleWhen` operators and
  evaluator (`evaluate_visible_when`, `hidden_fields`), `RADIO_OPTION_THRESHOLD`,
  `DATE_CONSTRAINT_KEYS` and `FORM_WEEKDAYS`, so a channel shows, hides and draws a form
  exactly as the answer check enforces it.
* **Inbound media faults** — `tai42_kit.net.media_faults`: catch
  `MEDIA_FETCH_AND_INGEST_FAULTS`, re-raise when `media_fault_is_transient(exc)` (so the
  vendor redelivers), else reject with `media_rejection_reason(exc)`;
  `inbound_media_kind_for_mime(mime)` maps a vendor mime type to the media kind.
* **Entry params** — `tai42_kit.conversations.entry_params.bound_entry_params(params,
  mode=..., door=...)` before `accept`: a door that answers a waiting caller passes
  `REFUSE` (the bound error is the caller's), a webhook door whose vendor redelivers a
  `5xx` passes `DROP` (the set is dropped, logged at `WARNING` and counted, and the turn
  proceeds). `put_entry_param` drops one over-cap value the same way.
* **Form shapes** — `tai42_app.interactions.form_shape_errors(question, values, fields=...,
  partial=...)` returns one `FormShapeError` (`field`, `kind`, `params`, `message`) per failing
  field, judged on the answer door's own schema; `fields` limits it to one step and `partial`
  leaves unfilled fields alone. `SHAPE_KEYWORDS`, `FormShapeKind` and `FormShapeError` live in
  `tai42_contract.interactions`, and the per-format regexes in
  `tai42_kit.interactions.FORMAT_PATTERNS`, so a channel draws and checks a shape exactly as
  the door does.
* **Deadlines** — no expired-delivery check in `deliver`: the dispatcher never hands one.

### Form capabilities per channel

Beyond the scalar fields and `format` controls above, a form's richer capabilities —
[multiple choice and radio](#multiple-choice-and-radio),
[date constraints](#date-constraints), [conditional fields](#conditional-fields),
[display blocks and a review page](#display-elements-and-a-review-page), and
[reacting while open](#forms-that-react-while-open) — each draw on every surface that
can render them, and **degrade by a documented rule** (never silently) where a surface
cannot. A capability a surface cannot draw either renders by the stated degrade or,
where there is no honest approximation, refuses loudly at the ask door.

| Capability | WhatsApp | Slack | Web chat | Telegram | SMS |
| - | - | - | - | - | - |
| date bounds (`minDate`/`maxDate`) | native picker bounds | **degrade**: enforced on submit | native `<input type=date>` min/max | native `<input type=date>` min/max | **refused** |
| unavailable days (`unavailableDates`) | native picker exclusions | **degrade**: enforced on submit | **degrade**: min/max drawn, the rest on submit | **degrade**: min/max drawn, the rest on submit | **refused** |
| date range (two date fields) | two date fields (may draw as one range control); each end's time a text field right after its date | two datepickers, each end's `timepicker` right after its date | two date inputs, each end's time right after its date | two date inputs, each end's time right after its date | **refused** |
| multiple choice (array of strings) | checkbox group | multi-select / checkboxes | multi-select | multi-select | **refused** |
| radio for a short list | radio group (`≤` threshold), else dropdown | radio (`≤` threshold), else select | radio (`≤` threshold), else select | radio (`≤` threshold), else select | **refused** |
| display block (heading/body/image) | text/image blocks | section/header/image/context | rendered block | rendered block | **refused** |
| review page | terminal summary screen | final summary group | review step | review step | **refused** |
| conditional field (`visibleWhen`) | client-side show/hide | reactive show/hide, else **degrade**: show all | client-side show/hide | client-side show/hide | **refused** |
| [reacts while open](#forms-that-react-while-open) | data endpoint | block actions → view update | session reaction door | ticket-page reaction door | **refused (loud)** |

The documented degrade rules:

* **Slack has no date-control bounds.** `minDate`/`maxDate` and `unavailableDates` are
  not drawable on its datepicker, so the author's constraint is **enforced on submit**
  (a per-field error keyed to the field), and re-rendered reactively where the form
  also [reacts](#forms-that-react-while-open). The author declares the constraint once;
  the platform guarantees enforcement, even where the control cannot visibly prevent an
  out-of-range pick.
* **A native HTML date input cannot disable arbitrary individual days.** It draws the
  `minDate`/`maxDate` bounds it can and enforces `unavailableDates` on submit; the same
  enforcement guarantee holds.
* **Slack has no native conditional field.** The platform re-renders the modal (a view
  update) to show or hide the field — this uses the channel's reactive **transport**,
  never the consumer's reaction handler, so it is independent of whether the form
  [reacts](#forms-that-react-while-open). Where a surface offers neither a client-side
  conditional nor a reactive transport, the documented degrade **shows every field** and
  the predicate still gates submit through the [effective-answer rule](#conditional-fields).
* **A surface that cannot draw an image** degrades a display block to its `alt`/body
  text, never dropping it.
* **SMS has no form surface.** A form question (and a reacting form) to an SMS channel
  is **refused loudly** at the ask door, before anything is sent.

Per the [effective-answer rule](#conditional-fields) and the single answer facet, a
degraded surface that draws a hidden field changes no outcome: the value is dropped on
submit. The **web chat** draws every capability above — it is a full form surface, not
a degraded one.

### When a channel reply doesn't match

On a chat medium the person can type anything, so a channel-delivered ask may receive
a reply the answer door **rejects** (a `400` — the reply doesn't fit the question's
format). What happens next is the ask's **`on_mismatch`** policy, set per ask by the
tool author:

* **`retry`** (the default) — the ask stays parked and the person is told what's
  expected, so they can answer again in place. The sender's `wording.answer.rejected`
  replaces the platform's built-in retry line with its own text, and
  `wording.answer.rejected_final` the line sent when a refusal also closes the question.
  A `{reason}` token in either is filled with the door's rejection reason by a plain
  substitution, and is empty when the door gave no reason. WhatsApp's re-sent form reads
  the sender's `wording.form.error_line` in that place when set. A channel that owns its
  own correction surface renders the door's specific reason itself.
* **`bridge`** — an unmatched reply is treated as a **digression**: the ask stays
  parked with **no** notice, and the reply is handed to the
  [conversation](/concepts/client-conversations) as a fresh routed turn so the flow
  handles it. The ask then ends only by a real answer or its timeout, never by
  unmatched input. `wording.answer.rejected` is not sent under this policy — a
  digression never notifies.

Both policies keep the ask alive; they differ only in whether an off-format reply
re-prompts the person or is routed onward as a new turn.

### Enrichment on the answer

When the person answers by **tapping** a control the channel offered, the tap may
carry channel-specific context back with the answer — the tapped option's author-set
`id`, a template button payload, a referral. A channel surfaces it as opaque
**`params`** on the answer (for example Slack forwards a tapped reply's id as
`params.reply_id`; WhatsApp surfaces its tap enrichment on the bridge path
instead), which the asking flow reads **beside** the `answer`. It is the
answer-path counterpart of the same enrichment a
[bridged conversation turn](/concepts/client-conversations) carries: bounded as
transport, carrying **no trust or meaning** the platform attaches — a plain typed
answer carries none.

## Forms that react while open

A form can **react while the person is filling it** — recompute a value, replace a
field's choices, show a per-field error, or fill a display slot — by naming a
**reaction handler** at ask time. The handler is a registered tool the consumer owns;
the platform runs it and validates what it returns, naming no consumer concept.

Two fields turn a form into a reacting one, both optional and defaulting to today's
static form:

* **`reaction_tool`** — the name of a registered tool run whenever a declared trigger
  fires. It runs through `run_tool` under the park's **rebound identity and state
  context** (the same the [continuation](#sync-and-async) uses), so a reacting form
  **must** be `mode="async"` with `answer_format="form"` — the request raises loudly
  otherwise.
* **`reactions`** — declares WHEN it reacts, as plain renderer-readable form
  description. Three event kinds, each absent by default:
  * **`field_changed`** — the input fields whose change triggers a reaction;
  * **`page_advanced`** — the page titles whose advance triggers one;
  * **`submitted`** — whether the submission is checked by a reaction before it is
    accepted.

```json theme={null}
{
  "schema": {"type": "object", "properties": {"day": {"type": "string", "format": "date"}, "slot": {"type": "string", "enum": ["09:00", "13:00"]}}},
  "reactions": {"field_changed": ["day"], "choices": ["slot"], "submitted": true}
}
```

A `reaction_tool` with no trigger, or a `reactions` block with no handler, is refused
— the two are halves of one declaration.

### The handler contract

The handler receives exactly three things: the `interaction_id`, the `event` (its
`kind` and the `field` or `page` it concerns — the contract's `FormReactionEvent`, received
as its JSON form), and the partial `values` filled so far.
It returns a **form update** — validated against this form's own schema before it
reaches the surface:

| Key | Fills | Validated |
| - | - | - |
| `values` | field values to set | declared fields only |
| `options` | choice lists to replace | option-bearing fields (string-enum or array-of-strings) only |
| `errors` | per-field error messages | declared fields only |
| `display` | display-slot values | declared [display slots](#display-elements-and-a-review-page) only |

A computed total is not a special case — it is a `display` slot the reaction fills.

### Reaction-fed choices

A reaction may **replace a field's choice list** while the form is open (the slots for
a date just picked, say). Such a field is named in **`reactions.choices`**. Because its
choices are no longer the ones the form was sent with, the platform's submit check
validates its **type only**, never membership in the send-time list — membership is the
consumer's, checked at the `submitted` event. A form declaring any `choices` field
therefore **must** also set `submitted: true`, or the request is refused loudly: an
unvetted reaction-fed value always meets a consumer submit check.

### A unique page title

A `page_advanced` trigger keys a page by its **title**, so a title shared by two pages
names an ambiguous advance. A `page_advanced` trigger on a form whose `pages` repeat a
title is refused at the ask door — give each page a unique title.

### The deadline, and failing loudly

The handler is bounded by a deadline (`INTERACTIONS_REACTION_DEADLINE_SECONDS`, default
`10`) at the single reaction chokepoint. A handler that raises, times out, or returns
an update naming a field or slot the form does not declare **surfaces loudly** — the
person sees the surface's error and the server logs it — never a stale or silently
dropped value. A reaction is **stateless for the durable record**: it never records an
answer, never resolves the interaction, and never rewrites the stored request. The
half-filled form lives on the surface until submission; the `submitted` event is where
the consumer accepts or refuses the whole form. The **server** runs the `submitted` check
on every answer door before it records — the authenticated answer door, the channel
callback, and a caller resume alike — so a surface that runs it first only shows errors
early and can never bypass it: the handler's per-field errors keep the form open, and only
a clean run records the answer.

### How a reaction reaches the handler, per surface

A reaction travels to the one chokepoint by the **same door that answers the form on
that surface**, by that surface's own correlation — the reaction door inherits the
answer door's model and adds nothing:

* **Web chat** — the web plugin's own session-authenticated, same-origin door, a
  sibling of its answer door; the ticket is kept server-side and never reaches the
  browser, and that door forwards the event server-side to the interaction's react
  door.
* **Ticket page** (the external-link page, and the webview a messaging channel opens) —
  the ticket in the page's address is the capability, so the page posts to the ticket's
  react door.
* **In-app** (`channel=None`) — the authenticated react door, a sibling of the
  authenticated answer door, under the same correlation and audience gate.
* **A messaging channel** — the vendor request authentication the channel already
  relies on inbound (WhatsApp's signed, encrypted data-endpoint request and the per-send
  flow token bound to the one interaction; Slack's signed request and view metadata).
* **SMS** — cannot react; a reacting form is refused at the ask door.

A surface advertises the reaction capability only when it really routes a reaction
end-to-end to that one chokepoint.

### Security

The reaction is reachable by whoever may answer the form **on that surface**, by that
surface's own correlation, and by nothing weaker — it inherits the answer door's model
of that surface and adds nothing of its own. Only the handler the asker named at ask
time runs, under the asker's rebound identity; the caller chooses neither the tool nor
the identity and supplies only this form's field values. A reaction is a
**read-and-compute** step — what the handler reaches is what that identity reaches,
exactly as the [continuation](#sync-and-async) does, and **effects belong to the
continuation after the answer**, not to the reaction. What comes back is only the
validated form update, bounded by the **same size and depth caps and request limits**
the answer door has.

### WhatsApp data endpoint (operator setup)

A reacting form, or one carrying a shape only the data endpoint can check, is published on
WhatsApp as a native Flow with a **data endpoint** Meta calls as the person fills it. The
endpoint decrypts each request, so before such a form can be published the operator
provisions the vendor's key material (loud failure when any is missing — such a form never
publishes silently inert):

* generate a business **RSA-2048 key pair**;
* set the **private key** as the secret `CHANNEL_WHATSAPP_FLOW_PRIVATE_KEY` (with
  `CHANNEL_WHATSAPP_FLOW_PRIVATE_KEY_PASSPHRASE` if the PEM is passphrase-protected) —
  it is never committed, and a fork configures its own;
* set `CHANNEL_WHATSAPP_FLOW_ENDPOINT_URI` to the public HTTPS URL of the plugin's data
  endpoint (`{public base}/api/channels/whatsapp/flow-data`);
* register the matching **public key** for the sending number — through the plugin's
  admin-only `POST /api/channels/whatsapp/flow-encryption` route on the running server,
  which derives it from the private key and registers it, so the operator copies no key
  material by hand.

A static WhatsApp form whose shapes the controls check themselves never touches this key
material. See the
[channel-whatsapp plugin page](/plugins/tai42/channel-whatsapp) for the full operator
steps.

## The doors

The interactions surface exposes nine HTTP doors. Five are authenticated and four
are public:

| Door | Auth | Purpose |
| - | - | - |
| `GET /api/interactions` | authenticated | paged list of pending questions (`page`/`pageSize`) |
| `GET /api/interactions/stream` | authenticated | tail-only SSE feed of live `add`/`answered`/`removed` frames |
| `POST /api/interactions/{id}/answer` | authenticated | the human answer door (in-client formats) |
| `POST /api/interactions/{id}/cancel` | authenticated | withdraw a pending ask without answering it (fires no continuation; the delivering channel releases its hold on the person and nothing is said to them) |
| `POST /api/interactions/{id}/react` | authenticated | the in-app [mid-form reaction](#forms-that-react-while-open) door (`channel=None`) — runs the reaction, records nothing |
| `GET /api/interactions/media/{id}` | **public** | serves media stored by reference — the id is the capability |
| `POST /api/interactions/callback/{ticket}` | **public** | the data door — sensitive answers ride the JSON body |
| `GET /api/interactions/callback/{ticket}` | **public** | the redirect door — serves a confirm or schema-rendered form page |
| `POST /api/interactions/callback/{ticket}/react` | **public** | the [mid-form reaction](#forms-that-react-while-open) door for a channel / ticket-page surface — runs the reaction, records nothing |

Publicness is an [access-control](/concepts/access-control) configuration decision,
not a property of the route code.

### Reading the stream

`GET /api/interactions/stream` is a **tail-only** SSE feed: on connect the server
starts from the events-stream tail and sends only live `add`/`answered`/`removed`
frames from that point on. It carries no historical backlog — a freshly opened
client seeds its pending list from the paged `GET /api/interactions` door, then
overlays the live tail.

Every event frame carries an SSE **`id:`** — the events-stream message-id, a
monotonic cursor. A client that reconnects sends the last id it saw back as the
standard **`Last-Event-ID`** request header (a `?last_event_id=` query parameter is
accepted as a fallback for a proxy that strips the header), and the server resumes
the tail **after** that id. So an event that landed during a brief disconnect — a
card's `answered` frame included — is delivered on reconnect instead of being lost
in the gap: a card the client was tracking converges to answered rather than
vanishing.

The resume window is the events stream's own bounded recent-events retention. When
the id is present but cannot cover the gap — malformed, or already aged out of that
window — the server falls back to the tail end and **logs** the fallback, so a
genuinely lost resume is never a silent skip; the client's connect-time refetch of
the paged pending base reconciles the rest. An **absent** id is a normal fresh
connect, not a lost resume: the server tails from the end and the same paged base
seeds the pending state, so this case is intentionally not logged.

## Security in brief

* **The ticket is the capability.** It is a high-entropy bearer token that expires
  on its TTL; single use is enforced by an answered-state guard, and a provider
  retry against a live ticket gets an idempotent `200 already_answered`.
* **GET never mutates.** Link scanners prefetch URLs, so the GET door serves a
  byte-constant confirm page — or, for a channel-delivered form, a page rendered
  from the stored schema — whose form POSTs back; the human's submit performs the
  claim.
* **Uniform 404 and no reflected input.** Unknown, expired, and pruned tickets
  return the same response; callback pages interpolate no request-derived value.
* **Signature verification** runs in core. Bind a
  [webhook verifier](/concepts/triggers-and-webhooks) to an external question and
  the POST door verifies the raw body before the answer is accepted — failing
  closed.

> [!NOTE]
>
> External questions require `INTERACTIONS_PUBLIC_BASE_URL` (an `https://` origin,
> since the callback URL is a bearer capability) and Redis 7.0+. Callback payloads
> arrive through an unauthenticated door, so every stream consumer must treat them
> as untrusted.

The [use-interactions guide](/guides/use-interactions) walks `ask` across the
answer formats and wires an `ask_external` callback end to end. See
[notifications](/concepts/notifications#ask-less-forms) for the ask-less form — the
non-blocking counterpart to a form ask — the
[HTTP API reference](/reference/api/index) for the interaction routes, and the
[CLI reference](/reference/cli/index) for `tai interactions`.


# jq variables
Source: https://docs.tai42.ai/concepts/jq-variables

The one rule for a jq's input and its named variables, and every variable the platform binds by jq site.

Many platform surfaces take an author-written **jq** program — a door mapping an
inbound message to a run's kwargs, a state binding shaping an update, a template
program. Every one follows a single rule for what the program reads.

## The rule

**The jq input `.` holds only the data the program is about. Everything the platform
adds beside it arrives as a named jq variable `$name`.** A door's `start_expr` reads
the inbound payload as `.` and the run's parked interactions as `$parked`; a state
update reads the tool's output as `.` and the run input as `$input`. A tool's output
is the update's `.`, never a `$output` variable — the data the program is about is
always `.`, and the variables are the context around it.

Each site declares exactly which variables it binds. A program that reads an
**undeclared** `$name` fails to compile at save, so a typo is a loud refusal rather
than a silent null.

> [!NOTE]
>
> The process environment is sealed out of every expression: the `env` builtin is
> disabled and `$ENV` is an empty object. The binding-mechanism names `__in`, `ENV`,
> and `__loc__` are reserved: they cannot be bound as variables, and a program that
> reads `$__in` is refused at compile. A value a program must
> trust comes from its declared input or variables, never the host environment.

## Doors

Every [door contract](/concepts/asking-the-caller#the-door-contract) expression — a
conversation route's, a hook's, or a schedule's `cancel_expr`, `resume_expr`,
`start_expr`, and `extras_expr` — reads the door's own input document as `.` and binds:

| Variable | Value |
| - | - |
| `$parked` | The run's currently parked interactions on the door's subject — the full entries [`list_parked`](/concepts/asking-the-caller#the-generic-tools) carries. |

## Route reply

A conversation route's [`reply_expr`](/reference/conversation-bridge#route-targets-agent-or-tool)
reads the started run's result as `.` and binds three variables:

| Variable | Value |
| - | - |
| `$turn` | The turn ids, subject and reply window this reply answers, `{id, inbound, subject, reply_window}` ([the turn block](/reference/conversation-bridge#route-targets-agent-or-tool)); `null` when an out-of-band delivery's originating record has aged out. |
| `$asks` | The run's caller-ask entries when it [asked its caller](/concepts/asking-the-caller) instead of finishing (each a full parked entry); an empty list on a plain result. |
| `$parked` | As above. |

## State bindings

A [state binding](/concepts/states#a-bindings-subject-and-scope)'s jq slots each read a
different `.` and bind the run's data as variables:

| Slot | `.` | Variables |
| - | - | - |
| `subject_expr` / `scope_expr` | the run input | — |
| injection `jq` | the attached record's subtree (or `{}` when no record exists yet) | `$input` — the run input |
| update `jq` (custom) | the run's output | `$input` — the run input; `$record` — the record subtree |
| update `adapter` | the run's output | `$input` |
| `op_id` | the run's output | `$input` |

## Template jq

A [template jq](/concepts/states#template-jq) program reads the record's attached
subtree as `.` and binds the attachment's context:

| Program | `.` | Variables |
| - | - | - |
| `input` | the attached record subtree | `$parameters`, `$declarations`, and its declared params as the single object `$params` |
| `update` | the attached record subtree | `$parameters`, `$declarations`, `$input` (the caller's argument) |

A template's **declarations check** reads the declaration values as `.` with
`$parameters` bound; its **reconcile** programs read their own data as `.` with, per
label, `$previous`/`$new` (`orphans`), `$id`/`$resolution` (`close`), or none
(`resolutions`).

## Flow authoring

A flow node's jq adds more variables on top of these — the state documents in scope,
the run's own identity, and, inside a loop, the iteration value and index. The flow
editor binds and documents them; see the
[flow jq editor](/babelfish/jq-editor) for `$states`, `$run`, `$iteration`, and
`$iterate`. The rule is the same everywhere: the node's own data is `.`, the context
around it is named variables.

## See also

* [Asking the caller](/concepts/asking-the-caller) — `$parked` and the door contract.
* [Conversation bridge](/reference/conversation-bridge) — a route's `start_expr` and `reply_expr`.
* [States](/concepts/states) — bindings and template jq.
* [Hooks](/concepts/hooks) — a hook as a door contract.


# The layering
Source: https://docs.tai42.ai/concepts/layering

How contract, kit, cli, skeleton, and Studio stack.

The platform is four Python packages linked by strict dependency edges, plus a
desktop UI over a running server. Each package depends only on packages nearer
the `tai42-contract` leaf, so the interfaces stay free of implementation and an
alternative server remains possible. Two edges run from the contract: the server
path (`tai42-contract` → `tai42-kit` → `tai42-skeleton`) and the command-line path
(`tai42-contract` → `tai42-cli` → `tai42-skeleton`).

```mermaid theme={null}
flowchart LR
    C["tai42-contract<br/>interfaces"] --> K["tai42-kit<br/>helpers"] --> S["tai42-skeleton<br/>the server"]
    C --> L["tai42-cli<br/>the tai command"] --> S
    U["Studio<br/>desktop UI"] -.->|drives over HTTP| S
```

## tai42-contract — the interfaces

`tai42-contract` is the pure interface leaf: protocols, ABCs, and pydantic models,
no logic. At runtime it imports nothing but `pydantic`, and its behaviour is a
narrow whitelist — the `tai42_app` forwarding handle, model validators, the storage
path guard, and `Agent`'s default stream drain. Vendor types (fastmcp, langchain,
starlette, mcp) appear only inside `TYPE_CHECKING` blocks, so they are never
loaded when the code runs.

Because the contract carries no implementation, a plugin author codes against
stable interfaces — the `Agent` ABC, the `Storage` ABC, the connector and
webhook-verifier protocols — and never against the server's internals.

## tai42-kit — the helpers

`tai42-kit` is generic leaf helpers: settings primitives, pooled clients, MCP
transports, LLM/embedding factories, the SSRF network guard with its safe URL
fetching, and structured-logging setup. Among tai42-\* packages its only dependency
is `tai42-contract` — it implements the contract's `BaseClient` protocol and
consumes its manifest types. The skeleton reuses these helpers rather than
re-declaring them.

## tai42-cli — the `tai` command

`tai42-cli` owns the `tai` command. On its own it is the standalone remote client:
thin groups over a server's `/api/*` routes, plus the CLI-native `completion` and
`version` commands, for operating a running server from any terminal. Among tai42-\*
packages its only dependency is `tai42-contract` — it never imports `tai42-kit` or
`tai42-skeleton`, so `pip install tai42-cli` puts the `tai` command on your path
with nothing of the server pulled in.

The command tree is open-ended: a server package contributes its own commands
through the `tai.commands` entry-point group, so the skeleton adds the local and
runtime commands (`serve`, `db`, `doctor`, …) onto the same `tai` tree when it is
installed alongside.

## tai42-skeleton — the server

`tai42-skeleton` is the framework body: the concrete `TaiMCP` server and the runtime
engines behind every contract protocol — the tool registry and adapters, the agent
registry, the OAuth connector engine, the access-control middleware, the hooks
router, the storage and template manager, the manifest loader, and the transport
layer. It depends on `tai42-contract`, `tai42-kit`, and `tai42-cli`, extending the
latter's command tree with its own local and runtime commands.

The app is constructed once and exposed as the `tai42_app` contract handle. Tools,
agents, and extensions register against it — the same handle every quickstart tool
uses:

```python theme={null}
from tai42_contract.app import tai42_app


@tai42_app.tools.tool
def greet(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"
```

## Plugins register through the handle

Providers — OAuth connectors, storage backends, config providers, worker
backends, monitoring — ship as separate [plugins](/concepts/config-and-secrets).
A plugin registers through `tai42_app` when the [manifest](/concepts/manifest)
loads its module; no plugin imports the skeleton. This is what keeps the core
free of provider code and the ecosystem open-ended.

## The Studio

The Studio is the desktop UI over a running server. It calls the same `/api/*`
HTTP surface the `tai` CLI calls, so anything you can do in the UI you can do from
a terminal, and vice versa. The [Studio section](/studio/index) tours its screens
— running tools, the admin console, and API-key provisioning.

See the [Python SDK reference](/reference/python-sdk/index) for the exact
public surface of `tai42-contract`, `tai42-kit`, and the skeleton.


# Live operations
Source: https://docs.tai42.ai/concepts/live-operations

Operate a server without a restart.

You operate a running server without a restart. Reloading a tool, replacing the
manifest, re-probing a failed MCP server, or removing a capability all happen live,
through the operations layer — one surface that projects to an HTTP route, a CLI
command, and (curated) an MCP tool.

## The operations layer

Every management capability is an **operation** — one decorated async function
that carries its own metadata: a name, a summary, the typed errors it may raise,
and flags such as `destructive`. An operation is the single source, and three
surfaces project from it:

* an **HTTP route** under `/api/*`, the door the CLI and the Studio drive;
* a **CLI command** in the [`tai` groups](/reference/cli/index);
* an **MCP tool**, registered through the normal tool binding so an
  [extension](/concepts/tools-and-extensions) wraps it, a [preset](/concepts/presets)
  bakes over it, and `tai tools run` or an agent dispatches it — subject to
  curation (below).

Because the three surfaces come from one declaration they cannot drift. The
management operations cover the live-ops families:

* **Tools** — re-register one app tool from its stored definition (`reload_tool`),
  drop a tool from the live registry (`remove_tool`), and run a registered tool by
  name (`run_tool`).
* **Config** — soft-restart in place by refreshing the environment and reloading
  the manifest registries (`reload_config`), and apply a whole
  [settings profile](/concepts/config-and-secrets#settings-profiles) — replace the
  stored env with a saved band, swap in a fresh serving epoch, and recycle any
  pooled resource the change tore down (`apply_profile`).
* **Manifest** — replace the whole persisted manifest, fleet-wide
  (`update_manifest`). The change is written through to durable config and then
  broadcast, so it survives a restart and reaches every worker.
* **MCP servers** — list the servers a viability check skipped (`list_failed_mcps`),
  re-probe and re-attach one server or every failed one (`reload_mcp`,
  `reload_failed_mcps`), and detach a server's tools by title (`deregister_mcp`).
* **Manifest sections** — add or remove a single `mcp`, `tools`, or `agents` entry
  by title (an add optionally replacing a colliding title in place), and add or
  remove names on the `api_tools` include/exclude lists — each a persisted,
  hot-reloaded edit to one item, so changing one entry no longer means rewriting
  the whole section.
* **Tool extensions** — attach or detach a single extension combo on a tool,
  leaving its other combos in place, alongside the whole-list write.
* **Access control** — add or remove one scope on a key, and set or remove one tag
  grant on a role — an item-level edit that never rewrites the whole scope set or
  grant map.

Drive them from the CLI:

```bash theme={null}
tai tools run <name> --kw name=World
tai mcp reload <title>
tai mcp failed
```

## Curating the MCP surface

Which operations project as MCP tools is set by the manifest's
[`api_tools`](/concepts/manifest#the-api_tools-block) block. Two exclusion tiers
guard the surface regardless of what a manifest asks for:

* **Tier 1 — never projectable.** A meta-executor — an operation that runs any
  tool by name, `run_tool` — is a universal authorization bypass, so it is
  hardcode-blocked from the MCP surface even when named in `api_tools.include`.
  It stays a route, the `tai tools run` command, and an internal dispatch target.
* **Tier 2 — off by default, includable.** An authority-changing operation — one
  that mints or scopes keys, edits policy, replaces the manifest
  (`update_manifest`), or restores unshipped state (a backup import) — is off the
  default MCP surface but projects when an `api_tools.include` names it explicitly.

A **destructive** operation carries a `destructiveHint` annotation on its
projected tool (and an `x-destructive` marker on its route in the
[OpenAPI spec](/reference/api/index)); it only projects when
`api_tools.expose_destructive` is on.

## Authorization on every MCP surface

`AuthzMiddleware` authorizes every projected-operation dispatch. It runs at tool
call time — before the extension chain, so before any backend enqueue — on every
MCP-serving instance: the main server and each [sub-MCP](/concepts/private-tool-sets)
mount. It resolves the dispatched tool to its base operation and, for a projected
operation, runs the access-control check; a denial raises a loud tool error. A
tool that is not a projected operation passes straight through — its authorization
is a separate concern.

## The mutation pipeline

A mutating operation runs one pipeline: it **validates** the change, **persists**
it transactionally to durable config, **reloads** the calling process, then
**broadcasts** it on the [worker bus](/concepts/worker-bus) and awaits a per-worker
outcome from every worker sharing the manifest. Persist-before-broadcast is why a
mutation survives a restart and why the persisted state and the live state cannot
drift apart through a supported path.

The broadcast reaches every process on the bus — serving HTTP workers and any
backend runtime alike — not just the one that received the request. Fan-out is the
app's own concern, carried by the bus; it is not a
[backend](/concepts/backends) capability. Every mutation response embeds the fleet
report, keyed per worker on its name, so a worker the change did not converge is
named — `departed`, `timed_out`, `missing`, or one of the gap outcomes
`resyncing`, `recycling`, and `stale` for a worker that was not in a ready,
freshly-beating state — never a fake success. A failed **local** apply raises; a
remote miss is reported and logged. Inspect the fleet and re-drive a reload with
the [`tai fleet` group](/operate/manage-a-fleet).

Because a mutation reaches every worker, the deployment shapes that run more
than one process need the bus: the boot rules refuse a multi-worker `tai serve`
server, a registered backend, or `kubernetes` mode without `TAI_BUS_REDIS_URL`. A
registered backend also needs a shared hooks registry (`HOOKS_REDIS_URL`, or
`TAI_DEFAULT_REDIS_URL`), so a mutation that adds a backend over an in-memory hooks
registry, or removes the hooks store while a backend remains, is refused at the
validate step, naming `HOOKS_REDIS_URL`; the same holds for the bus. A multi-worker
`tai serve` server also needs shared sub-MCP and hooks stores, so a mutation that
would leave it without the bus or with either store in-memory is refused at the
validate step too, naming the setting.

A [settings-profile](/concepts/config-and-secrets#settings-profiles) apply extends
this pipeline at the reload step: instead of refreshing in place it builds a fresh
serving **epoch** off to the side under the proposed env and swaps it in atomically,
retiring the old one — a failed build is discarded with the old surface still
serving. This same epoch build backs a plugin install or upgrade: any reload that
rebuilds the serving surface re-imports each plugin package and its route-sibling
modules and re-registers the declared routes, so a plugin's HTTP surface — a
router or middleware, a channel's inbound webhook — comes live on the epoch swap
of the reload that changed it rather than waiting for a process restart. Before it commits, an epoch route audit
compares the rebuilt route set against the outgoing one and refuses to swap in an
epoch that would silently drop a still-declared plugin's routes; the prior epoch
keeps serving and the failure is surfaced. For a changed key whose reload class is
`recycle`, it then orchestrates a
process recycle across the fleet, on the shapes that support one. Its report is
per worker: each recycled row carries a status and the `generation_before` it was
recycled from, alongside a per-kind list of the fresh lives that have since
joined. Confirmation is by reality, not successor identity — a recycle is accepted
on two facts: the targeted old lives are **gone** (their slots absent, expired, or
already at a higher generation), and **fresh ready capacity** of each kind has
booted under the new config, counted per kind to cover the recycled workers.
The targets are the workers on the census when the apply started together with those
on it when the roll begins, so a worker that briefly dropped off the census is waited
for rather than skipped. A row that is not `recycled` is where the roll stopped:
`timed-out` (within the step budget the old life did not go or fresh capacity did not
boot, or the target never returned to ready) or `failed` (the worker refused the op,
or the bus could not be reached while it was in hand), with a `detail` naming why; the
roll also stops when the bus cannot be read before a target is reached. The response's
`recycle_stopped` names where the roll stopped and why: its `name` is empty when the bus
could not be read before a target was reached, and it is `null` when every target
recycled. Later targets and the applier's own recycle are then not attempted, and the
call still answers `200` with the report, as every fleet mutation does.

## Reloading is a first-class state

While a reload is in flight, the routes that dispatch a run or mutate live
registries return a retriable `503` carrying a reloading marker and a `Retry-After`
header, rather than serving against a half-swapped registry. A client treats it as
a transient condition and retries — the reload is a state the API describes, not an
error.

The refusal holds on every door that schedules a conversation turn, not only on the
API's own message and event routes: a channel webhook (a vendor's inbound message, the
web chat's send) that arrives during a reload is answered the same retriable `503`, and
nothing of it is recorded, so the vendor's redelivery is processed in full. A
conversation door tool reached off the HTTP gate — from a hook, a schedule, an agent's
tool call, or a detached run — fails loudly with the `unavailable` error kind instead of
running, and is retried only where the tool's retry policy opts in.

A plugin route opts into the same refusal by declaring `reload_gated` on its
registration; the route surface enforces it around the handler.

## Soft restart

`reload_config` is the soft restart: it refreshes environment values and reloads the
manifest registries in place. Combined with [live config](/concepts/config-and-secrets)
and manifest updates, it lets a server pick up configuration and capability changes
without dropping its process. Across a fleet, `tai fleet reload-config`
soft-restarts every worker on the bus (or only `--target` ones) and returns the
per-worker report — see [Manage a fleet](/operate/manage-a-fleet). The soft restart
never respawns a process, so a recycle-class value changed in the stored env outside
the pipeline (a hand edit of `.env`, a `kubectl edit` of the config Secret) is named by
the reload instead: each worker's report lists it under `awaiting_respawn` (its value
differs from the one the worker bound — at boot, or when the plugin that declares it was
loaded), the worker
that ran the reload command logs one ERROR line naming every such worker, and it takes
effect when that worker is respawned through the deployment's supervisor (on a bare
server, a restart). The response of an env write or a profile apply names under
`awaiting_respawn` the workers still awaiting a respawn after its roll — empty when the
roll converged.

## The kinds summary

A server reports which pluggable kinds it actually resolved at startup. Every
kind — [identity and accounts](/concepts/accounts) providers, monitoring,
storage, backend, channels, webhook verifiers, config, and Studio plugins — gets
one status row, in three states:

* **active** — a real plugin is registered and serving the kind.
* **default** — nothing is configured, but a built-in fallback is serving in its
  place (the no-op monitoring recorder, or the file config provider). The kind
  works; it is just running on the built-in.
* **off** — nothing is registered and the kind has no built-in fallback. This is
  a legal, reported state, not an error.

The same rows surface three ways: printed as a `[kinds]` summary block in the
server's startup log (and again after any in-place reload), served at the authed
`GET /api/system/kinds` route, and rendered in the Studio's [System kinds
table](/studio/admin-console#the-kinds-table). Read them from a terminal with:

```bash theme={null}
tai system kinds
```

One state carries an explicit heads-up: when monitoring is running on its
**default** (the no-op recorder — no monitoring plugin installed), the startup
summary logs a **one-time** warning that runs are not being recorded and
observability dashboards will read zeros. It fires at most once per process — the
point where "monitoring not configured" becomes distinguishable from "no traffic
yet" — so a monitoring-less deployment is flagged without spamming the log on
every reload.

See the [observe guide](/operate/observe) for watching a live server and the
[HTTP API reference](/reference/api/index) and [CLI reference](/reference/cli/index)
for the management routes and commands.


# The manifest
Source: https://docs.tai42.ai/concepts/manifest

The declarative file a server loads at startup.

The manifest is the single declarative file a server loads at startup. It names
the tools, agents, extensions, external MCP servers, and plugin modules that make
up one running system. Nothing loads automatically — a capability is present
because the manifest names it.

> [!NOTE]
>
> This page covers the **server** manifest. A plugin's own descriptor,
> `tai-plugin.yml`, is a different file.

## Where it comes from

A server loads its manifest from the file pointed at by `--manifest-path` (its
env default is `TAI_MANIFEST_PATH`), or from its config directory. An empty
manifest (`{}`) boots a bare MCP server with no tools; every section is optional.
The manifest is parsed strictly: an unknown key, at the top level or inside any
block, is refused by name, so a mistyped key fails the load instead of leaving the
field you meant at its default.

```bash theme={null}
tai serve --manifest-path examples/hello/manifest.yml
```

Before you deploy, validate a manifest offline — no server required — with the
CLI:

```bash theme={null}
tai manifest validate manifest.yml
```

## What it holds

Most entries are Python import paths. Importing a module runs its `@tai42_app.*`
registration decorators, which is how a tool, agent, or provider becomes live.

* **`tools`** — each entry imports a `module` and selects tool names with
  `include` / `exclude`. A separate `extensions` map attaches an
  [extension](/concepts/tools-and-extensions) branch to a selected tool.
* **`agents`** — each entry imports a module whose `@tai42_app.agents.agent`
  decorator registers an [agent](/concepts/agents) and generates its run tool.
* **`mcp`** — external [MCP servers](/guides/bring-an-mcp-server) to mount, one
  transport per entry (`url`, `uds`, or `command`).
* **Startup module hooks** — single-valued slots and module lists that wire
  plugins in: `storage_module`, `backend_module`, `monitoring_module`,
  `extensions_modules`, `lifecycle_modules`, `routers_modules`,
  `middlewares_modules`, `webhook_verifier_modules`, and `channel_modules`.
  `routers_modules` names only extra HTTP routers mounted on top of the default
  set; `default_routers` selects that set ([below](#http-routers)).
* **`studio_plugins`** — names the installed Python **packages** that ship a
  [Studio plugin](/studio/plugins) (a browser-side UI extension), not import
  paths. Each named package carries its own `studio-manifest.json` declaring what
  it contributes to the Studio shell — tool panels, pages, settings tabs, and
  sidebar `nav_entries`. That plugin manifest is a separate file from this server
  manifest; see [Author a Studio plugin](/studio/plugins).
* **`api_tools`** — curates which management [operations](/concepts/live-operations)
  project as MCP tools (below). It never selects your own tools; it governs only
  the operation-projected surface.

## A minimal manifest

The hello-world manifest names one local tool module and nothing else:

```yaml theme={null}
tools:
  - title: hello
    module: myapp.tools
    include: [greet]
```

`module` is an import path, so `myapp` must be importable when the server starts.
`include` limits which tool names from the module are exposed; omit it to expose
all of them.

## Selection versus attachment

Within a `tools` entry, `include` / `exclude` are **selection** only — they decide
which tool names go live. The `extensions` map is **attachment** — it branches a
selected tool into a new variant (`{toolname: [ext]}` produces `toolname_ext`).
Attachment never selects: mapping an extension onto a tool that is not in the
selected set raises loudly rather than silently doing nothing.

## The `api_tools` block

The management [operations](/concepts/live-operations) — reload a tool, replace
the manifest, re-probe a failed MCP server — are always available as HTTP routes
and CLI commands. `api_tools` decides which of them also project as MCP tools:

```yaml theme={null}
api_tools:
  enabled: true
  expose_destructive: true
  include: [update_manifest]
  exclude: [reload_config]
```

* **`enabled`** — with `false`, no operation projects as a tool; the surface is
  empty.
* **`expose_destructive`** — gates the destructive-flagged operations (a tool
  reload, a manifest replace). With `false` they stay off the MCP surface even
  though their routes remain.
* **`include`** / **`exclude`** — name operations to force on or suppress. A name
  appearing in **both** lists is a loud validation error, and an `include` naming
  an operation that is not registered fails boot rather than silently doing
  nothing.
* **`extensions`** — attaches [extension](/concepts/tools-and-extensions) combos to
  a projected operation, exactly as a `tools` entry's `extensions` map does.

Two rules override the block. A **meta-executor** — `run_tool`, which runs any
tool by name — is never projectable: it is hardcode-blocked from the MCP surface
even when named in `include`. An **authority-changing** operation — one that mints
keys, edits policy, replaces the manifest (`update_manifest`), or restores
unshipped state (a backup import) — is off the default surface and projects only
when `include` names it explicitly.

## HTTP routers

Out of the box the server mounts a **default core-router set** — every built-in
API router, plus the Studio SPA catch-all served last — so a bare manifest boots
the full Studio surface. You do not list the core routers. `default_routers`
selects the set:

* **`all`** (the default) — mount the core API routers and serve the Studio SPA,
  whose catch-all route is added last. The normal full-Studio deployment.
* **`api`** — mount the core API routers but do not serve the SPA: a headless
  JSON HTTP API (`/api/*`) with no browser UI.
* **`none`** — mount no defaults; `routers_modules` must then list every router
  the server loads. For a fully manual or MCP-only surface.

A feature's runtime lifecycle does not depend on the router selector. Under every
value the server registers the conversations completion tools and, with a
conversations Redis configured, re-drives unfinished conversation records and runs
the periodic delivery sweep. The marketplace advisory poll starts only where
`GET /api/marketplace/advisories` is served — under `all` and `api`, or under `none`
with `tai42_skeleton.routers.marketplace` listed in `routers_modules`.

`routers_modules` is always **additive**: it names extras — your own routers, a
plugin's router — mounted on top of the selected default set. Under `all` and
`api` the loader mounts each core router once even if the manifest re-lists it, so
an extra never double-mounts a default.

The module list decides **which** modules load; a plugin's own descriptor decides
**where** its routes mount. An installed router or channel plugin
[declares its routes](/concepts/marketplace#declared-http-routes) — a relative
`base` prefix and the rows under it — and the installer records both the module (in
`routers_modules` or `channel_modules`) and the chosen mount `base`. Every route
resolves at `/api/` + `base` + its path, so listing the module never picks the URL:
the declaration does, and the operator can remap the `base` at
[install](/marketplace/install#mount-the-routes). Your own router modules carry no
descriptor, so they mount their handlers' absolute paths as written. A plugin route
that would collide with one the core or another plugin already owns is refused at
registration, never silently shadowed.

The Studio SPA catch-all matches every unclaimed path, so it must register **last**
or it shadows the routers after it. Under `all` the loader forces it last, and an
installed plugin router is inserted before it. Under `none`, where you list routers
yourself, keep the SPA catch-all module last in `routers_modules` if you serve the
Studio UI.

> [!NOTE]
>
> Tool extensions still load per module — you opt each one in by naming its module,
> exactly like your own code. The management tools are a further exception: they
> project from the operations layer, curated by `api_tools`, not loaded module by
> module.

See the [Python SDK reference](/reference/python-sdk/index) for the `Manifest`
and `ApiToolsConfig` models and the [CLI reference](/reference/cli/index) for
`tai manifest`.


# The marketplace
Source: https://docs.tai42.ai/concepts/marketplace

The plugin index: listings, items, versions, and advisories.

The marketplace is the ecosystem's plugin index. A running server browses it,
installs a plugin from it in one command, and hears from it when a published
version turns out to be bad.

This page explains the model. To search it and install from it, start at
[Marketplace](/marketplace).

## A metadata index

The registry stores metadata, never packages. A **listing** points at the
plugin's real distribution channel — usually a pip package and a source
repository, or, for a descriptor-only plugin, the `tai-plugin.yml` itself — and
installing resolves that pointer and installs by source: a
GitHub-sourced release is downloaded and its SHA-256 verified against the
digest the registry recorded at ingest, while a PyPI-sourced release pins the
exact version and relies on PyPI's file immutability. A third source, `spec`,
backs a [descriptor-only listing](#delivery-package-or-descriptor) that ships no
package at all — its artifact is the `tai-plugin.yml` itself, pinned at its tag
and digest. The registry's catalog is curated: it lists the ecosystem's
first-party plugins, and every listing carries an `official` trust tier.

## Listings and items

One installable plugin carries many capabilities: a single package can ship
tools, extensions, and agents together. The registry indexes each contained
capability as its own **item** row with a kind, categories, and tags — because
an item is what you search for. You search at item level and install at plugin
level: finding the `generate_uuid` tool leads you to install the listing that
carries it.

An item's **kind** decides how it wires into a server, and it also decides
whether the item is **code** or **data**. Most kinds are code: the item names a
Python module the server imports. Two kinds are data — `mcp-server` and
`connector` — where the item carries a declarative block (an MCP transport entry,
or a connector's [provider descriptor](/concepts/connectors)) instead of a module,
so nothing has to be imported to register it. That data-versus-code split is
independent of how the plugin is **delivered**, below.

## Versions

Each listing publishes **versions**. A version records the exact release, its
artifact, and the [tai42-contract](/concepts/layering) compatibility range it
declares, so a server can tell whether a release fits its contract before
installing. The registry validates every release's artifact against its
listing before publishing it — a release that fails validation is never
served.

## Advisories and the kill switch

An **advisory** flags affected versions of a listing with a severity and a
summary. Separately, a version can be **killed** — a registry-side kill switch
that refuses to resolve that version at all, so it can never be installed. The
two are distinct: an advisory is a published warning that can later be
withdrawn, while a killed version is pinned out of resolution.

See [Advisories](/marketplace/advisories) for how a server checks.

## The plugin descriptor: tai-plugin.yml

Every plugin describes itself with a `tai-plugin.yml` — the plugin descriptor —
at its repository root and, when it ships one, inside its built wheel. It names
the listing, the version, the contract range, the `provides` list of every item
the plugin carries, and — for a plugin that owns database tables — the
`migrations` folder that holds its [migration chain](#the-migrations-contract).
It also names the `package`, the pip distribution that backs the listing — but
`package` is **optional**: a plugin whose every item is data can omit it and
ship no code at all (see [Delivery](#delivery-package-or-descriptor)).

The registry indexes a plugin from this file and validates the artifact against
it; the installer uses the `provides` list to patch the server
[manifest](/concepts/manifest) per provided item. It is a different file from the
server manifest: `tai-plugin.yml` describes what a plugin *offers*, the server
manifest declares what a server *loads*.

## Delivery: package or descriptor

A listing carries two independent axes. **Payload** is what each item *is* — code
or data, decided by its kind (above). **Delivery** is how the plugin *arrives*,
and it is set by one field: `package`.

* **Package delivery** (`package` present) — the listing points at a pip
  distribution. Installing pip-installs it into the server's environment, exactly
  as every code plugin does. A data plugin may still ship a package: an
  `mcp-server` whose command is a console script the wheel installs, for example,
  is data-payload *and* package-delivered. Delivery is independent of payload.
* **Descriptor delivery** (`package` absent) — a *descriptor-only plugin*. Every
  item is data, so there is nothing to import and nothing to pip-install. The
  registry lists it with `source: spec`: the artifact is the `tai-plugin.yml`
  itself, pinned at its tag and digest, with no wheel and no PyPI lookup. Today a
  [connector](/concepts/connectors) ships this way — a whole OAuth integration as
  one descriptor, no code.

`delivery` is derived, never declared: it reads `descriptor` when `package` is
absent and `package` when it is present, and every surface — the CLI, the Studio,
and the marketplace detail — shows that one word so you always know whether an
install will touch the environment.

## Declared HTTP routes

A plugin that mounts HTTP routes — a `router` item, or a `channel` item with an
inbound webhook — **declares** them in its descriptor rather than wiring absolute
paths in code. A `router` item must carry a `routes` block; a `channel` item may;
no other kind does. The block is two parts:

* **`base`** — the item's default mount prefix, relative and template-free (one or
  more `[a-z0-9-]` segments joined by `/`). The resolved absolute path of every
  route is `/api/` + `base` + the route's own `path`. The `/api/` root is fixed
  platform-wide; only `base` moves, and the operator can remap it at
  [install](/marketplace/install#mount-the-routes) — always, and as the collision
  remedy.
* **`paths`** — the route rows. Each row is a `path` relative to `base`, a
  non-empty `methods` list, and a required `public` flag. A `path` is `/`-prefixed
  with at least one segment; a segment is a literal or a `{name}` template. `public`
  has no default — the declaration always states whether the resolved route answers
  unauthenticated.

```yaml tai-plugin.yml theme={null}
spec_version: 1
namespace: acme
name: alerts-relay
package: acme-alerts-relay
version: 1.0.0
description: Relays inbound alerts into the assistant.
license: MIT
contract: '>=10.0,<11'
categories: [channels]
provides:
  - kind: router
    name: relay
    module: acme_alerts_relay.routes
    description: An inbound alerts webhook and its status read.
    routes:
      base: alerts/relay
      paths:
        - path: /inbound
          methods: [POST]
          public: true
        - path: /status/{event_id}
          methods: [GET]
          public: false
```

Here the webhook resolves to `/api/alerts/relay/inbound` (public, so it answers
without a credential) and the status read to
`/api/alerts/relay/status/{event_id}` (authed). The item's route module registers
each handler against the **relative** `path`; the declaration decides the absolute
mount and the public-ness, so the code never hardcodes either.

Each declared route has **one owner**. Two routes collide when their resolved path
*shapes* overlap — same segment count, and at every position both are the same
literal or one is a template — and they share a method (`GET /api/x/{id}` overlaps
`GET /api/x/foo`; a different method or a different segment count never collides).
The server refuses to register a route that collides with one a different plugin or
the core already owns, and [install](/marketplace/install#a-collision-is-a-remap)
surfaces the clash up front with remap as the remedy. How a declared `public` route
is served without a credential is the [declared-public
tier](/concepts/access-control#routes-declare-their-own-public-ness).

The route module's own registration declares the rest of a route's reach. A login or
recovery route passes `pre_auth=True` (it must be `public`): a stale credential the
browser still presents is then ignored there instead of refused. An identity-introspection
route passes `any_authenticated=True` (it must be authed), and a caller self-service
route under `/api/auth` passes `self_service=True` so the seeded roles carve it in. See
[routes declare their reach](/concepts/access-control#routes-declare-their-reach).

The registration also declares what the platform reads about a route rather than
guesses:

* **Flood control** — a public route's `DeclaredRouteMetadata` may name its
  `rate_limit_family` and the family's `rate_limit_budget`
  (`RateLimitBudget(limit=…, burst=…)`). A declared family holds whatever base the
  install remaps. Every public route of one family declares the same budget; a plugin
  whose routes disagree fails the boot, or the reload that installs it, loudly. See
  [budgets](/concepts/access-control#budgets).
* **Success media types** — `success_media_types={"GET": ("text/html",)}` publishes the
  body each method really answers in the OpenAPI document; a method left out publishes
  `application/json`.
* **Reloads** — a route declaring `reload_gated=True` answers the retriable reload `503`
  while a configuration reload runs; the platform enforces it around the handler, so the
  route carries no check of its own. A route that hands a turn to the conversation bridge
  needs no flag: the bridge refuses the turn during a reload and the platform answers the
  same `503`.

## The migrations contract

A plugin that owns tables ships its schema as a **migration chain**, not a
one-shot DDL apply. The framework runs the chain: `tai db migrate` discovers every
component — the core plus each installed plugin that declares one — and applies
its pending files in order. A plugin author owns the files; the runner owns the
mechanism.

**Declare the folder.** Point the descriptor's `migrations` field at a directory
packaged inside the wheel:

```yaml tai-plugin.yml theme={null}
package: tai42-accounts-postgres
migrations: migrations
```

**Number the files.** Each file is `NNNN_short_name.sql` — one or more leading
digits, an underscore, a name, the `.sql` suffix — applied in ascending numeric
order. A `.sql` file that does not match the pattern, or two files claiming the
same number, is a loud discovery error, never a silent skip.

```text theme={null}
migrations/
  0001_baseline.sql
  0002_add_invite_index.sql
```

**The chain's component identity.** By default the chain is recorded in the
per-database `tai_schema_history` table under the plugin's **distribution name**
(`package`) — for the accounts plugin, `tai42-accounts-postgres` — and that
default identity never changes across releases, so the runner always reads the
exact rows earlier versions wrote.

A plugin whose feature store is a **separate database component** rather than the
distribution itself may instead declare an explicit `migrations_component` naming
that component (declaring it requires `migrations`; a component with no chain
migrates nothing). A component-scoped chain runs only while that component's
[database binding](/concepts/config-and-secrets#component-bindings) is explicitly
declared: with the binding set, the chain migrates that component's store under the
declared name; with it unset, `tai db migrate` **visibly skips** the chain — the
skipped chain is named in the command's result (both its table and JSON output)
and the command exits non-zero, so an operator and any automation see that a
declared chain did not run rather than assuming a clean migrate. `tai doctor` reports the
same skipped chain. So the store stays off until an operator opts it in by declaring its
binding.

**Checksum immutability — never edit a shipped file.** The runner records a
SHA-256 of every applied file. On the next migrate or [boot gate](/self-hosted/upgrades#the-boot-gate)
check it re-verifies each recorded version against the file that produced it; a
changed checksum reads as a **rewritten chain** and is a hard error, never a
silent re-run. A shipped migration is immutable. A correction — even a typo — is a
**new** numbered file appended to the chain, never an edit to the old one. Chains
roll forward only; there are no down-migrations.

**Breaking changes: expand then contract.** Because there is no down-migration and
older replicas may still be running during a rollout, split a breaking change
across releases rather than rewriting a column in place:

1. **Expand** — add the new shape additively (a new nullable column, a new table)
   in one migration. Old and new code both run against it.
2. **Backfill and cut over** — ship code that writes both shapes, or backfills the
   new one, until every replica is on the new release.
3. **Contract** — in a later release, once nothing reads the old shape, add a
   migration that drops it.

Each step is its own numbered file, so the chain records the whole transition and
a from-scratch replay reproduces it exactly.

## Installing into a server

Install is a server-side operation: the server resolves the listing, installs
the verified package into its own environment, patches its manifest per
provided item, and reloads. The server records the marketplace ref and installed
version locally, so `installed`, update checks, and advisories answer from
local truth. The whole flow is one CLI command or one Studio click — see
[Install a plugin](/marketplace/install).

Because the install writes into the server's own environment and manifest, a
self-hosted deployment keeps both on persistent storage — the plugin-prefix
directory and the manifest file — so a container recreation does not lose the
plugin. See [the persistent mounts](/self-hosted/quickstart#the-persistent-mounts).

### Installing a descriptor-only plugin

A [descriptor-only listing](#delivery-package-or-descriptor) installs with no pip
run: the server resolves the frozen `tai-plugin.yml`, patches the manifest — a
connector adds one entry to the manifest `connectors` list — and reloads. Nothing
lands in the environment except the config it needs.

Because there is no package to carry secrets, a descriptor states the environment
it needs and the server refuses to write it half-configured. The install
**preview** computes the `required_env` for the listing — each variable as
`{name, secret}` — and the `missing_env` still absent from the server. The Studio
install dialog reads those and prompts for the missing values, seeding the secret
toggles from `required_env`; the CLI takes them as flags:

```bash theme={null}
tai plugins install tai42/connector-acme \
  --env CONNECTORS_ACME_CLIENT_ID=... \
  --env CONNECTORS_ACME_CLIENT_SECRET=... \
  --secret CONNECTORS_ACME_CLIENT_SECRET
```

`--env KEY=VALUE` supplies every value; `--secret KEY` is a bare mark that keeps a
value masked and out of logs (a connector's client secret is auto-marked too, and
`--secret` stays available for any key you want hidden). An install that would
leave a required variable unresolved is refused up front, naming the variables,
before anything is written.

Installing a descriptor mutates the running server the same as any install, so it
sits behind the same **admin-only** trust boundary: scope the
`/api/marketplace/*` routes with [access control](/concepts/access-control), and
treat a descriptor's `official` tier the way you treat a code plugin's — a
first-party connector is a curated, admin-installed integration, not an
open door.

## See also

* [Browse and search](/marketplace/browse) — find plugins and items.
* [Install a plugin](/marketplace/install) — install, update, uninstall.
* [The manifest](/concepts/manifest) — the server-side file the installer patches.
* [Plugins](/plugins) — every listed plugin, read from the marketplace.


# The MCP-citizen surface
Source: https://docs.tai42.ai/concepts/mcp-citizen-surface

MCP-native features and the FastMCP escape hatch.

A tai server is a first-class MCP citizen. The MCP-native features — output
schemas and structured content, elicitation, progress, sampling, completions, and
native tags — are all reachable, and anything the platform's facets do not wrap is
reachable through one escape hatch to the raw underlying FastMCP server.

## Built on FastMCP

The skeleton's server is a FastMCP server underneath. The platform layers its own
governance over it — [manifest](/concepts/manifest) gating, the extension registry's
validation, and the [access-control](/concepts/access-control) gate — and exposes
its features through typed facets. The MCP-native capabilities ride the FastMCP
foundation, so an MCP client gets structured content, progress, elicitation, and
the rest as it would from any MCP server. An elicitation a tool raises in process, with
no MCP client to answer it, is answered through `ask` instead, in the inbox; its accepted
result carries the `_meta` key `tai42/reply_to`, which is `null` because the answer did
not come over a channel (see [an elicitation answered through
`ask`](/guides/use-interactions#an-elicitation-answered-through-ask)).

The server's management tools are not hand-registered on this surface: they
project from the [operations layer](/concepts/live-operations), curated by
[`api_tools`](/concepts/manifest#the-api_tools-block). An `AuthzMiddleware`
installed on this FastMCP instance and on every [sub-MCP](/concepts/private-tool-sets)
mount authorizes each projected-operation dispatch before the tool runs.

## The `app.fastmcp` escape hatch

For anything the facets do not wrap, the app exposes the raw FastMCP instance
directly:

```python theme={null}
from tai42_skeleton.app.instance import app

raw = app.fastmcp   # the raw, ungoverned FastMCP server
```

Reach here for what the facets deliberately leave to FastMCP — prompts, resources,
`add_middleware`, sampling, elicit-handlers, completions, server metadata such as
`name`/`version`/`auth`, and the process-global `fastmcp.settings`.

> [!WARNING]
>
> Anything registered **through** `app.fastmcp` skips the platform's governance:
> manifest gating, the extension registry's validation, and the access-control gate.
> Prefer the facets; use the escape hatch only for what they do not cover. It is named
> `fastmcp` (not `mcp`) so it does not read as the [sub-MCP](/concepts/private-tool-sets)
> namespace, `app.sub_app`.

The accessor is intentionally not on the `TaiApp` contract protocol — the contract
stays FastMCP-free so an alternative implementation of the platform remains
possible, which makes this accessor skeleton-specific.

## FastMCP's own capabilities

The platform documents the escape hatch — what the `app.fastmcp` field is and what
it grants — not FastMCP's own API. For a deep dive into FastMCP's prompts,
resources, middleware, and the rest, see FastMCP's documentation at
[gofastmcp.com](https://gofastmcp.com).

See the [Python SDK reference](/reference/python-sdk/index) for the `app.fastmcp`
field and the platform's facets.


# Member actions
Source: https://docs.tai42.ai/concepts/member-actions

Provider-declared member-admin actions the platform renders and routes without knowing what any of them mean.

An [accounts provider](/concepts/accounts) declares the member-admin actions it
supports; the platform renders and routes them without knowing what any action
means. The Members surface reads that declaration to offer page buttons and
per-row menus, and a single invoke door performs one on demand. A provider adds,
renames, or removes an action by changing its declaration alone — no platform
code and no bespoke route moves with it.

## Declared, not built in

A provider returns its actions as data, each one a small descriptor the platform
treats generically:

* **id** — the provider's own token for the action. The platform never parses or
  branches on it; it only carries it back to the provider that declared it.
* **label** — the wording shown in the UI, resolved to a plain string at the
  catalog door through the platform's [templated-text](/concepts/storage-and-resources)
  path, so it localizes like any other wording.
* **scope** — where the action renders: `page` (acts on no existing row),
  `member_row` (acts on one member), or `invite_row` (acts on one outstanding
  invitation). A closed set every member view has a place for.
* **destructive** — whether the surface asks the caller to confirm first.
* **input schema** and **result schema** — the JSON Schema of what the action
  takes and what it returns. The platform renders a form from the input schema
  and a read-only view from the result schema; it reads no field of either.

Because the platform holds only the descriptor, any accounts provider's actions
appear on the same Members surface with no platform change — the capability is
part of the accounts contract, not a feature of one provider.

## Two doors

Both doors live under the reserved `/api/auth` namespace and are **admin-only**:

* `GET /api/auth/member-actions` lists the deployment-wide catalog — every
  registered provider's declared actions, each as a descriptor with its rendered
  label, scope, destructive flag, and input and result schemas.
* `POST /api/auth/member-actions/invoke` performs one action, named by its
  catalog key, against an optional target row, with an input body.

The catalog is what the Members page renders its buttons and menus from; the
invoke door is what a button or menu item calls.

## Opaque keys and handles

A caller never names a provider. The catalog gives each action an opaque
**action key**, and each row in the [Members directory](/concepts/accounts)
carries an opaque **routing handle**. Both are tokens the platform mints and
decodes to route a call back to the provider that owns the action and to the row
it acts on; a caller echoes them, never parses them.

To invoke, a caller sends the action key, the target row's handle (omitted for a
`page` action), and the input. The platform decodes the key to its provider and
action, decodes the handle to its target, refuses a malformed token or a key and
handle that name different providers with a `400`, and hands the call to the
provider.

## Validation and typed failure

The input is validated against the action's declared input schema before the
provider runs. A declared field with the wrong type is a `422` that names the
offending field paths; an unknown key is ignored.

A provider reports a correctable failure as a typed error, which the door maps to
a status — a conflicting state is a `409`, an unknown target a `404`, a bad
request a `400` — so a caller can tell a correctable failure from a server fault
instead of meeting an opaque `500`. On success the platform serializes the
provider's result generically and reads no field of it: whatever the action
produces — including a one-time value shown only once, such as a sign-in link —
surfaces on the invoke response and nowhere else.

## Member state stays platform-owned

A member's **disabled** state and **role** are access-control facts the platform
owns, not something a provider reports. A provider's member record carries the
[principal](/concepts/access-control) id (or ids) the person holds; the Members
operation joins those ids against the platform's own records and takes each
principal's `disabled` state and the role it holds from there. A row exposes each
principal's state and two derived values: `disabled` is true only when every
principal the person holds is disabled, so a person with any live principal still
reads active; `role` is the one role every principal holds, and `null` when there
is no single one — every principal's access was set directly, or the principals
hold different roles. A person whose logins hold different roles is listed with
each login's own role, never refused. A principal id a provider names that the
platform does not hold is a loud failure, never a guessed state.

An invitation holds no principal yet, so its role is the one the provider reports:
the role the person will hold.

## See also

* [Accounts](/concepts/accounts) — the provider kind that declares these actions
  and the Members directory they render against.
* [Access control](/concepts/access-control) — the principal records the disabled
  state is joined from, and the admin fence both doors sit behind.
* [User types and permissions](/concepts/permissions) — the roles an action
  assigns and the admin-only route fence.
* [HTTP API reference](/reference/api/index) — the `/api/auth/member-actions`
  doors.
* [Accounts contract reference](/reference/python-sdk/contract-accounts) — the
  `MemberAction` declaration a provider returns.


# Notifications
Source: https://docs.tai42.ai/concepts/notifications

Send a one-way message to a person — to an in-app inbox, an external channel, or both.

A notification is a **one-way** message to a person. It is the counterpart to an
[interaction](/concepts/interactions): where `ask` suspends the caller and
blocks for an answer, `notify_user` delivers a message and returns immediately,
waiting on nothing.

`notify_user` is a projected **operation tool**, so an agent or tool with it in
scope can send one — and it is the same capability behind `POST /api/notifications`
and the [`tai notifications notify`](/reference/cli/notifications) CLI command.

## Two destinations

A notification lands in either or both of two places:

* **The in-app inbox** — a per-deployment feed the Studio and the API read back.
  Every notification is recorded here.
* **An external channel** — when `channel` names a registered
  [channel plugin](/plugins) (Telegram, Slack, WhatsApp, Twilio, web), the message
  is also pushed to a person on that medium.

Omitting `channel` records the notification to the inbox only. Naming a channel
that is not registered is a loud error, never a silent drop.

## What a notification carries

| Field | Effect |
| - | - |
| `message` | The text shown to the person. Required; it may be blank only when `media` or `location` carries the content (a content-only send). |
| `channel` | A registered channel to deliver on. Omit to record to the inbox only. |
| `recipient` | The per-call **delivery address** on that channel — a chat id, a phone number. Omit to use the channel's operator-default recipient. |
| `audience` | The **identity** whose in-app inbox shows the record (see below). |
| `media` | Display media sent with the message — `image`, `document`, `video`, and `audio` file items plus labelled `link` anchors (see [media kinds](#media-kinds-and-typed-options)). Requires a channel that advertises media support. |
| `location` | A shared geographic point — latitude/longitude with an optional place `name` and `address`. Requires a channel that advertises location support. |
| `template` | A pre-approved out-of-window [template](#out-of-window-templates) send, addressed by its `name` + `language` with **named components** (a media header, positional body values, per-button arguments). Requires a channel that advertises template support. |
| `options` | A flat list of tappable [typed options](#media-kinds-and-typed-options) (at most 10) — a `reply` (its text becomes the person's next message) or a `link` (opens a URL). Requires a channel that advertises interactive support. |
| `sections` | The sectioned alternative to `options` — titled groups of reply rows (rows summed across sections stay within 10). Requires interactive support. |
| `header` / `footer` | A single media `header` above, and a short text `footer` below, an interactive message. Each requires `options` or `sections`. |
| `schema` | An [ask-less form](#ask-less-forms)'s answer schema. The channel renders `message` as the form's prompt and `schema` as the fillable form; the submission enters the conversation as an ordinary message from the person. Requires a named channel that advertises form support. |
| `data` / `pages` | Per-send [prefill, choice lists, and step layout](/concepts/interactions#prefilling-per-send-options-and-pages) over `schema` for this one send — `data.values` opens the form filled in, `data.options` replaces a string property's choices for this send, and `pages` lays the form out in titled steps. Both ride ONLY a form send (a `schema` present) and are cross-checked against it. |
| `form_tag` | An optional opaque **correlation tag** for this one form send: the channel carries it with the form and hands it back beside the submission (see [correlating a send](#correlating-a-send-with-its-submission)). Rides ONLY a form send (a `schema` present). |

A send on a channel with a [bridge route](/concepts/client-conversations) for the sending
identity is also recorded in the recipient's conversation thread, as a [send
record](/reference/conversation-bridge#send-records) — whether it came from a flow, the
tool or the API, and whether or not a turn was running. A send made during a turn to that
turn's participant is placed in the turn's thread. With no route, or no conversations
store, the send goes out unrecorded.

With a named channel, the richer forms deliver only where the channel advertises the
matching capability; with no channel, `media`, `location`, `template`, `options`, and
`sections` are stored on the inbox record as given — `schema` alone **requires** a
named channel (`400` without one): the internal sink has no delivery vehicle to render
a form and no submission door for its answers, so a stored form nobody could submit is
refused up front, never recorded. The composition rules are:

* **One choice surface.** `options` **XOR** `sections` — a flat button list or a
  sectioned list, never both.
* **One interactive surface.** `schema` (a form) excludes both `options` and
  `sections` — a message carries a form or a choice list, never both.
* **`header`/`footer` compose a choice surface.** Each requires `options` or
  `sections` present.
* **`template` stands alone.** The out-of-window send is mutually exclusive with every
  other content and interactive field — `media`, `location`, `options`, `sections`,
  `schema`, and (transitively) `header`/`footer`.
* **`media` and `location` combine freely** with a choice surface or a form: a card
  with a tappable list beneath it, a form with display media above it, a pin beside a
  choice.

A form or a choice needs a prompt, so `schema`, `options`, and `sections` each require
a non-blank `message` (only a content-only `media`/`location` send may leave the
message blank). A channel that does not advertise the matching capability rejects the
send with `501 not supported` rather than silently downgrading it to text.

> [!NOTE]
>
> The sending identity a channel message leaves **from** is set only by the
> [conversation bridge](/reference/conversation-bridge), never by a caller — a
> caller-supplied sender is refused with a `400`.

## Media kinds and typed options

**Media** is a list of `MediaItem`s, each a `kind` + `url` + optional `caption`. The
file kinds — `image`, `document`, `video`, `audio` — carry a fetchable body (an
absolute `https` URL, a same-origin `/api/interactions/media/<id>` served reference,
or, for `image` only, an inline `data:image/*` URI); a `link` is a labelled `http(s)`
anchor the person clicks through. A `document` item may also carry a **`filename`** —
the suggested display name the medium shows for the download; it is meaningful only on
a `document` and is refused on any other kind.

**Options** are a **typed, discriminated** list — the clean break from the old
text-only `list[str]`. Each entry is one of two shapes, tagged by `kind`:

```json theme={null}
{"kind": "reply", "text": "Yes, book it", "description": "Confirms the 3pm slot", "id": "confirm-3pm"}
{"kind": "link",  "label": "Open the docs", "url": "https://docs.example.com"}
```

* A **`reply`** is a quick-reply / list-row: tapping it **submits `text`** as the
  person's next inbound message, exactly as if they had typed it. `description` is an
  OPTIONAL secondary line a sectioned-list row renders under its `text` (a channel
  that renders flat buttons ignores it — see the [matrix](#channel-capability-matrix)).
  `id` is an OPTIONAL author-set stable identifier: when set, the channel sends it
  verbatim on the wire and the person's tap **echoes it back** to the inbound turn as
  `params.reply_id` (opaque enrichment a [conversation](/concepts/client-conversations)
  tool target reads beside the message); when omitted the channel mints its own id.
* A **`link`** is a call-to-action button: tapping it **opens `url`** in the browser
  and submits **no** message — distinct from a reply.

### Sectioned lists, headers, and footers

`sections` is the sectioned alternative to a flat `options` list: titled
`OptionSection` groups, each holding reply rows only (a link is a button, never a list
row). Use it to group a longer choice under headings; the rows summed across every
section still obey the 10-option cap. A message carries `options` **or** `sections`,
never both.

An interactive message may also carry a **`header`** — a single display-media item
(image/document/video/audio, never a link) shown above it — and a **`footer`**, a
short trailing line beneath it. Each composes a choice surface, so both require
`options` or `sections` to be present.

### Location

`location` shares a geographic point — `latitude`/`longitude` in WGS84 decimal
degrees, with an optional place `name` and street `address`. A channel that renders
maps drops a native pin; one that cannot renders the coordinates (and any
name/address) as text. It combines with a choice surface or a form, and a
location-only send may leave `message` blank.

### Out-of-window templates

`template` is a pre-approved `ChannelTemplate` for delivery **outside** a medium's
freeform window (e.g. WhatsApp's 24-hour customer-service window). It is addressed by
`name` + `language` and parameterised by its **named components**, never a flat
positional list:

* `header_media` — the media argument for a media header component (a display item,
  never a link);
* `body_parameters` — the positional body-text values substituted into the body's
  placeholders in order (typed values ride as their pre-formatted strings);
* `buttons` — the positional per-button arguments (a quick-reply `payload` or a URL
  suffix), the i-th entry parameterising the i-th button.

> [!NOTE]
>
> The named-component shape is a **clean break**: the old flat `parameters` list is
> **removed**. A template's runtime arguments are `header_media`, `body_parameters`, and
> `buttons` — nothing else.

## Channel capability matrix

Every shipped channel renders the shared vocabulary as far as its medium allows and
**declines** — never silently downgrades — a shape it cannot render: a send of an
unadvertised capability is refused loudly (`501 not supported`) so content is never
dropped. Where a medium lacks a native construct but can approximate one, the channel
**degrades honestly** rather than declining. The support each channel advertises:

| Shape | [WhatsApp](/plugins/tai42/channel-whatsapp) | [Web chat](/plugins/tai42/channel-web) | [Telegram](/plugins/tai42/channel-telegram) | [Slack](/plugins/tai42/channel-slack) | [Twilio](/plugins/tai42/channel-twilio) |
| - | :-: | :-: | :-: | :-: | :-: |
| `media` — image | native | inline | `sendPhoto` | image block | MMS `MediaUrl` |
| `media` — document/video/audio | native, per item | download card / native players | `sendDocument`/`Video`/`Audio` | labelled link line¹ | `MediaUrl`; document → `filename: url` line |
| `media` — link | appended to body | outbound anchor | inline with body | labelled link line | body line |
| `options` (reply / link) | reply buttons or list; link → CTA URL button | tappable chips; link → button | inline keyboard | Block Kit buttons | **declined** |
| `reply.description` | list-row secondary line | secondary line | `params.reply_description`² | folded into a context block | — |
| `reply.id` → `params.reply_id` | yes | yes | yes | yes | — |
| `sections` | multi-section list | titled groups | grouped buttons, title as text header³ | section header + reply buttons | **declined** |
| `header` / `footer` | media header / text footer | media header / muted footer | header as caption or a separate message; footer as a trailing italic line | image block / muted context block | **declined** |
| `location` | native pin | map-pin + OpenStreetMap link | `sendLocation` / `sendVenue` | section + OpenStreetMap link | **declined** |
| `template` | native (named components) | **declined**⁴ | **declined** | **declined**⁵ | **declined**⁶ |
| `schema` (ask-less form) | native Flow (in-window)⁷ | form card | **declined**⁸ | **declined**⁸ | **declined**⁸ |
| `form` **question** delivery (`ask`)⁹ | Flow | web widget | webview of the callback form page | Block Kit modal | **declined** |
| a form field's `format`¹⁰ | `date` → native date picker; `time`/`date-time` → text | `date` → `<input type="date">`; `time`/`date-time` → text | `date` → `<input type="date">`; `time`/`date-time` → text | `date` → `datepicker`; `time` → `timepicker`; `date-time` → text | **declined** |

¹ Slack has no `files.upload` seam here, so a `document`/`video`/`audio` item degrades
to a labelled link line rather than an uploaded file.
² Telegram carries a bridged tap's author-set `id` back as `params.reply_id` and a
sectioned row's `description` as `params.reply_description`.
³ Telegram has no native sectioned list, so `sections` degrade to grouped buttons with
each section title rendered as a text header.
⁴ ⁵ ⁶ A `template` is a **vendor** construct (a pre-approved WhatsApp template
referenced by name/language). Web chat, Slack, and Twilio have no such registry to
render one into, so they decline the capability outright.
⁷ On WhatsApp a form notification is a native Flow, and — like every freeform send —
only inside the provider's 24-hour customer-service window; an out-of-window form
notification fails loudly, never downgraded.
⁸ Telegram and Slack deliver a form **question** (`ask` with
`answer_format="form"`) but not an ask-less form **notification**: an ask-less form is
ticketless and their form vehicle (a callback page / a Block Kit modal) needs an ask's
ticket machinery to open. SMS has no form vehicle at all.
⁹ A form's [`pages`](/concepts/interactions#prefilling-per-send-options-and-pages)
render per medium: WhatsApp gives each page its own Flow screen; the web widget and
Telegram's callback-page webview show them as steps with a progress line; Slack, having
no native multi-step modal, lays the pages out as titled sections within the one Block
Kit modal. A form's per-send `values` and `options` ride the same vehicles — prefilled,
and offered in place of the schema's `enum` — and a channel that cannot honor them
refuses the send, naming the field.
¹⁰ A `string` form property may carry a `format` of `date`, `time`, or `date-time`; each
medium renders its native control where one exists and a plain text input where none does,
and the ask door validates the submitted shape either way (`date` `YYYY-MM-DD`, `time`
`HH:MM` or `HH:MM:SS`, `date-time` an RFC 3339 timestamp with a `Z` or `±HH:MM` offset).
The full per-surface mapping is the [rendering table](/concepts/interactions#delivering-to-a-channel).

`reply.description` support is **channel-dependent**: WhatsApp list rows render it and Slack folds it into a muted context line; Telegram never displays it and instead echoes it back as `params.reply_description` on a bridged tap, and a channel that renders only flat buttons ignores it.

A form's **richer field capabilities** — [multiple choice and radio](/concepts/interactions#multiple-choice-and-radio), [date constraints](/concepts/interactions#date-constraints), [conditional fields](/concepts/interactions#conditional-fields), and [display blocks and a review page](/concepts/interactions#display-elements-and-a-review-page) — render on an ask-less form exactly as on a form question, each by the surface that can draw it and by the documented degrade where it cannot: the [form capabilities per channel](/concepts/interactions#form-capabilities-per-channel) table holds the full matrix and the degrade rules. [Reacting while open](/concepts/interactions#forms-that-react-while-open) is the one form capability an ask-less form never has — a reaction rides the interaction's ticket machinery, which a ticketless notification does not mint.

## `audience` versus `recipient`

These are two orthogonal axes, and both may be set at once:

* **`audience`** is the *identity* whose scoped in-app inbox surfaces the record.
* **`recipient`** is the *delivery address* on an external channel.

Setting `audience` is honored even when a channel `recipient` also delivers the
message — you get both the external push and the in-app entry. `audience` is the
same field, with the same isolation rules, that `ask` uses: a restricted
[owned key](/concepts/owned-keys#audience--one-concept-across-interactions-and-notifications)
addresses only its own slice and cannot broadcast, and addressing another identity
is refused with a `403`. See
[owned keys](/concepts/owned-keys#audience--one-concept-across-interactions-and-notifications)
for the full read/write isolation model.

## Ask-less forms

Passing `schema` — a [JSON-schema form](/concepts/interactions#delivering-to-a-channel)
in the same channel-deliverable subset a channel-delivered form question uses — turns
the notification into an **ask-less form**: the channel renders `message` as the
form's prompt and `schema` as the fillable form, and the send returns immediately,
exactly as every notification does.

```bash theme={null}
tai notifications notify "fill this in" --channel whatsapp \
  --schema '{"type": "object", "properties": {"name": {"type": "string"}}}'
```

What comes back is **not an answer** — nothing is waiting for one. A submission
enters the conversation as an **ordinary message from the person**, riding the same
inbound path a tapped option takes: rendered text as the message every consumer
sees, with the structured values beside it for a
[conversation route's tool target](/concepts/client-conversations#structured-participant-messages)
to map deliberately. There is **no interaction, no ticket, no expiry, and no
validation loop**: unlike a form [ask](/concepts/interactions), nothing blocks,
nothing re-prompts on a bad value, and the platform never checks the submission
against the schema — the values are **participant-shaped data**, bounded as transport
(size and nesting) but carrying no more trust than typed participant text. A tool that
consumes them validates them itself.

### Correlating a send with its submission

A flow may have several ask-less forms of the same kind open at once. Set an optional
**`form_tag`** on the send to tell their submissions apart: it is a short opaque string
you choose (non-blank, `^[A-Za-z0-9_.~-]{1,64}$`). The channel carries it with that one
form and hands it **back unchanged** beside the submission's [`form` and
`params`](/concepts/client-conversations#structured-participant-messages), so the route
reading the submission knows which send it answers.

The tag is **per send** and **opaque** — the platform never interprets it, only bounds
it as transport, and refuses it on a send that carries no `schema`. It is never shown to
the person, carries no personal data, and never enters the published Flow. It rides the
tool and the API only, like [`audience`](#audience-versus-recipient).

A sent message is also findable by its provider message ids. On a channel with a
delivery-status webhook, the receipt for a recorded send settles its send record and is also
posted to the run's trace as the `delivery_receipt` event; a receipt for a send outside any
conversation still reaches the trace.

When to use which: a form **ask** (`ask` with `answer_format="form"`) suspends
the caller until a validated answer or an expiry — reach for it when the flow cannot
proceed without the answer. An ask-less form sends the form and moves on — reach for
it when the submission is welcome whenever (and however often) it arrives, as each
submission is simply the person's next message.

On the **web chat** the form renders as a card in the transcript. Like the option
chips it has no deadline and no answered state: submitting shows a local "Sent"
badge, the card stays fillable (each submission is its own participant message), and an
expired form shows an inline "no longer available" line:

![The web chat form card rendering a prompt and a schema-driven form with text, choice, and number fields above a send button.](https://mintcdn.com/tai42/xdHOAbW9fRf-H_xp/images/channel-web/form-card-light.png?fit=max\&auto=format\&n=xdHOAbW9fRf-H_xp\&q=85\&s=87b584a0a302e871d70a1954a7d5f620)

The web chat's ask-less form card — the prompt, the schema-rendered fields, and the send control.

On **WhatsApp** the form delivers as a native Flow — and, like every freeform send,
only inside the provider's 24-hour customer-service window. An out-of-window form
notification **fails loudly** (synchronously or as a `failed` delivery status),
never silently downgraded to a template or to text.

With an `audience`, the in-app record stores the `schema` alongside the message,
so the feed shows what was asked for — but the inbox record itself is never
submittable, which is why a form notification with no channel is refused.

## Reading the inbox

The inbox is read on demand — there is no streaming surface. List the recorded
notifications newest-first:

```bash theme={null}
tai notifications list
```

or `GET /api/notifications`. A restricted caller reads only its own `audience`
slice; an unrestricted operator reads the shared feed. The feed is a bounded,
newest-first ring: it retains a fixed maximum number of entries and trims the
oldest past it. It rides on the [interactions](/concepts/interactions) Redis store,
so a deployment with that store unconfigured cannot record and lists an empty
inbox.

### Entries the platform writes

Besides the notifications tools and doors send, the platform writes entries of its own to the
shared feed (no `audience`, so every unrestricted operator reads them) when an operator must act:

* `A pending state save failed; its subjects are held until it is retried or discarded. Save {id}, run {run}, phase {phase}: {error}` — see [pending saves](/concepts/states#pending-saves).
* `Pending state save {id} was discarded; its writes and calls will never be applied.` — an
  operator discarded a failed save.

When the feed cannot take such an entry (its store is unconfigured, or the write fails), the
platform logs an ERROR naming the save and counts it in
`tai42_state_outbox_notify_failures_total`.

> [!NOTE]
>
> The CLI `tai notifications notify` exposes `--channel`, `--recipient`, `--media`,
> `--template`, `--options`, `--sections`, `--location`, `--header`, `--footer`, and
> `--schema` (each rich form a JSON string validated into its contract model), but **no
> `--audience`** — addressing a specific identity is available on the tool and the API
> only.

## See also

* [Interactions](/concepts/interactions) — the blocking counterpart, `ask`, and
  the form **ask** an ask-less form contrasts with.
* [Owned keys](/concepts/owned-keys#audience--one-concept-across-interactions-and-notifications) — the `audience` isolation model in full.
* [Client conversations](/concepts/client-conversations) — the channels a notification
  pushes to, and the structured participant message a form submission arrives as.
* [CLI reference](/reference/cli/notifications) — the full `tai notifications` surface.


# Owned keys
Source: https://docs.tai42.ai/concepts/owned-keys

Delegation as a capped sub-identity: attenuation, the capability projection, and per-identity isolation.

An **owned key** is an API key minted by a user and capped by that user forever.
It is the delegation primitive: a credential you hand to a teammate, a device, or
a machine that acts *as you, but lesser* — it can never do more than you can, and
it loses power the moment you do. Where [access control](/concepts/access-control)
is the request gate and [accounts](/concepts/accounts) are the humans behind it,
owned keys are the layer that lets one identity safely lend a slice of its
authority to another.

This page explains the model. To mint one and hand it over, follow
[Use owned keys](/guides/owned-keys).

## What an owned key is

Every owned key carries an **owner** — the account that minted it, recorded on the
key's identity record as an owner claim. That single claim is what makes the key
*owned* rather than free-standing, and it drives three properties:

* **Minted by an owner.** A non-admin mints, from its account session, only keys
  owned by itself; an admin may also mint a key for a **service principal** (see
  [accounts](/concepts/accounts)). Ownership is exactly one level deep — an owned
  key can never itself mint keys.
* **Capped by the owner.** The key's scopes are a subset of the owner's, enforced
  at mint time and re-checked on every request. A mint that asks for a scope the
  owner does not hold is rejected with a `400` at mint time, never a silently
  narrowed key.
* **Dies with the owner.** Because the cap is re-applied per request, disabling or
  narrowing the owner attenuates the key on its very next call — no revocation of
  the key itself required.

## Attenuation over time

An owned key's **effective authority is its own grant intersected with its owner's
*current* policy**, computed fresh on every request at the gate. The key does not
carry a frozen snapshot of what its owner could do when it was minted:

* Move the owner from an editor role to a viewer role and every key that owner
  holds is re-evaluated against the narrower policy on its next request.
* Disable the owner, or empty the owner's scopes, and every owned key is denied —
  the key is powerless while the owner is down, and recovers if the owner is
  restored.

This is why an owned key is safe to hand out: the ceiling follows the owner
automatically, so you revoke a person once (their account) rather than chasing
down every key they were ever issued.

## The capability projection

An owned-key holder needs to know what it may actually do — otherwise a scoped key
meets a wall of `401`/`403`s with no way to discover its own limits. `GET /api/auth/me`
answers that: the caller's **derived capability projection**.

```bash theme={null}
tai auth whoami
```

The projection reports the caller's own `user_id`, its owner (if any), whether it
is an admin, its effective scopes, and the concrete **routes, route patterns,
sub-MCP mounts, tools, and agents it can reach right now** — plus a `mintable`
flag. Two properties make it trustworthy:

* **Derived, never stored.** The projection is computed from the *same*
  `access_control_routes` store and policy the gate reads, filtered by the caller's
  effective scopes. There is no second access-control list that could drift from
  the gate. It is cached per policy version and identity, so a policy edit yields a
  fresh projection on the next read.
* **jq-exact.** For a policy that carries a jq condition, the projection evaluates
  the *same* condition per candidate `(path, method)` through the real enforcer, so
  it never advertises a door the gate would then deny. The projection is a subset
  of what the gate admits, by construction.

Because introspection must work for every identity on every deployment, `GET /api/auth/me`
is **authenticated-implies-allowed**: an authenticated caller reaches it regardless
of the route table (an unauthenticated caller still gets a `401`). It stays under
the reserved `/api/auth` prefix — it is never public.

> [!WARNING]
>
> The always-allowed carve-out bypasses only the route **table**, never jq. The gate
> evaluates a policy's jq condition first. The seeded `editor` and `viewer` roles
> already carry a `/api/auth/me` carve-in, so they work out of the box. But if you
> write a **custom** jq condition that fences the `/api/auth` namespace, you must add
> a `/api/auth/me` carve-in to it — otherwise every owned key under that condition
> `403`s on `/me` and its [scoped Studio](/studio/api-keys) bricks. This is inherent:
> jq is your own lever, and the carve-in covers only the seeded roles.

## Data isolation

An owned key is **restricted**: any identity whose claims carry an owner is confined
to its **own slice** of the data-bearing surfaces, while unrestricted identities —
admins and editor/viewer role-holders — keep the full operator view (their limits
come from scopes and jq fences, not isolation). This single
mechanical test — *does the identity carry an owner claim?* — is the whole isolation
boundary; there is no new stored type field.

A restricted caller sees only its own slice of three surfaces — and that slice is
the key's **own identity**, never its owner's. Same-owner keys do not share a slice
and cannot see each other's activity; each key is its own island.

* **Tool runs**, keyed on the run's owning identity — the caller's *own* key
  identity (`get_current_user_id()`), not its owner. A restricted caller lists and
  reads only the runs its own key submitted, and a fetch of any other identity's run
  — including one belonging to a sibling key under the same owner — is a `403`.
* **[Interactions](/concepts/interactions)**, keyed on `audience` (below).
* **Notifications**, also keyed on `audience`.

### `audience` — one concept across interactions and notifications

`audience` is **the identity a message is addressed to** — the same field, with the
same meaning, on both `ask` (interactions) and `notify_user` (notifications).
It drives the same own-slice-only read on the interactions inbox *and* the
notifications inbox: a restricted caller sees only messages whose `audience` is its
own key identity; a message with no `audience` is an operator/broadcast, shown to
unrestricted callers but not to restricted ones. The write side mirrors this. When a
restricted caller *sends* with no `audience`, the field is auto-scoped to its own key
identity — so the message lands in (and reads back from) its own slice rather than
broadcasting — and an attempt to address *another* identity is refused with a `403`,
the write-side dual of the read isolation.

Do not confuse `audience` with a notification's channel **`recipient`**. They are
two orthogonal axes, and both may be set at once:

| Field | Axis | Meaning |
| - | - | - |
| `audience` | identity | *whose in-app Studio inbox shows it* |
| `recipient` | delivery address | *where to push it externally* (a chat id, a phone number) |

Setting `audience` is honored even when a channel `recipient` is also set — you get
both the external push and the in-app inbox entry. Two honest notes for tool
authors:

* **`audience` is a routing hint, not an authorization input for reads.** Reads
  authorize by the *caller's* identity, and unrestricted operators always see
  everything, so addressing a message can neither hide it from operators nor expose
  another identity's data. For an unrestricted caller, `audience` only chooses whose
  scoped inbox surfaces it.
* **A restricted caller addresses only its own slice — it cannot broadcast.** The
  slice is keyed on the caller's *own* key identity, so leaving `audience` unset
  auto-scopes the send to that key itself: an unaddressed `notify_user` or `ask`
  is recorded to — and read back from — the caller's own scoped inbox, never dropped
  and never a broadcast. Any *other* `audience` — a foreign identity, including the
  key's own owner — is a cross-identity attempt rejected with a `403`, and is never
  escalated to operators. An owned key therefore notifies itself simply by leaving
  `audience` unset; it never sets an id to reach its own inbox.

> [!NOTE]
>
> To run a **restricted machine key**, an admin mints it as an owned key with the
> owner set to the admin. A `*` owner caps nothing, so attenuation is a no-op — but
> the isolation rule still applies, so the machine key sees only its **own** slice:
> the runs and addressed messages of that key itself, never its owner's and never a
> sibling key's. Ownership is thus how you get an isolated automation identity, not
> only a human-delegated one.

## Access channels

The ways an owned key reaches a caller are a **defined, closed list** — only
industry best practice, with the rejected shapes recorded so they are never
"conveniently" added later.

**1. Programmatic API**

The key travels in an `Authorization: Bearer <key>` or `X-Api-Key` header.
Header-only is law — a credential never appears in a query parameter, a URL
path, or a body at rest.

**2. MCP client**

The same key in an MCP client's header config, against the main `/mcp` endpoint
or a scope-gated [sub-MCP mount](/concepts/mcp-citizen-surface).

**3. Browser UI (the scoped Studio)**

The key pasted at the [Studio sign-in](/studio/login) page and held in the
browser. The Studio renders from the projection, so a scoped key sees only the
features it can reach — one UI for everyone, no separate portal.

**4. QR / deep-link claim**

A one-time, short-TTL **claim link** — `<origin>/login#claim=<token>`. The token
rides the URL **fragment**, so it never reaches a server log; the browser (or
`tai auth claim`) exchanges it once at the always-public `POST /api/login/claim`,
receives the raw key exactly once (the token then burns), and proceeds as the
browser channel. See the [owned-keys guide](/guides/owned-keys).

> [!WARNING]
>
> **What we deliberately do not offer.** These shapes are recorded so they stay
> rejected:
>
> * **Anonymous, long-lived capability URLs to execution surfaces.** Langflow's
>   anonymous shareable-playground links became the cautionary case here — they drew
>   published security advisories for unauthenticated remote code execution and
>   arbitrary file read. A claim link is the opposite: single-use, short-TTL, and it
>   exchanges for a *real revocable identity* rather than being a standing anonymous
>   door.
> * **Credentials in query params or URL paths** — they land in logs and browser
>   history.
> * **The raw key inside a QR image** — the QR carries a single-use claim token, never
>   the credential itself.
> * **Cookie/session login for keys** — stateless keys remain the model.

## Scope doctrine

Isolation makes some read scopes safe to grant to owned keys, and leaves others
strictly operator-only. Grant an owned key only the scopes in the **safe** column;
the others expose account-wide data or let an owned key mutate a shared namespace it
does not own.

| Scope family | Safe to grant to an owned key? | Why |
| - | - | - |
| Tool runs (read) | **Yes — isolated** | A restricted caller sees only its own key's runs — its own island, keyed on the key's own identity, never shared with sibling keys under the same owner. |
| [Interactions](/concepts/interactions) (read/answer) | **Yes — isolated** | Scoped to the caller's own `audience`. |
| Notifications (read) | **Yes — isolated** | Scoped to the caller's own `audience`. |
| [Observability / traces](/operate/observe) | **No** | Trace payloads are full tool and model inputs/outputs, account-wide. |
| [Storage / resources](/concepts/storage-and-resources) | **No** | A shared namespace — an owned key would read and mutate content it does not own. |
| [Presets](/concepts/presets) | **No** | Shared, unowned definitions; a mint is an account-wide mutation. |
| [Schedules](/concepts/triggers-and-webhooks) | **No** | An owned key would create or edit unowned, account-wide schedules. |

Per-resource ownership for the operator surfaces is not offered — the boundary is
deliberately "own slice on the isolated surfaces, operator-only everywhere else."

## See also

* [Access control](/concepts/access-control) — the request gate, scopes, and the jq
  policy model owned keys are capped by.
* [Accounts](/concepts/accounts) — owners, roles, and who may mint what.
* [Use owned keys](/guides/owned-keys) — mint a capped key, inspect it, and share it
  by QR claim link.
* [CLI reference](/reference/cli/auth) — `tai auth whoami`, `tai auth claim`, and
  [`tai keys claim-link`](/reference/cli/keys).
* [HTTP API reference](/reference/api/index) — `/api/auth/me`, `/api/auth/claim-links`,
  and `/api/login/claim`.


# User types and permissions
Source: https://docs.tai42.ai/concepts/permissions

The identity types, what each may reach, and how a request is judged.

Every request reaching a server is judged as one of a small, fixed set of
identity types. This page names those types, shows what each may do across the
feature surface, and explains the composed layers that produce the verdict.
It builds on [access control](/concepts/access-control) (the request gate),
[accounts](/concepts/accounts) (the humans behind it), and
[owned keys](/concepts/owned-keys) (capped sub-identities).

## The model at a glance

Before the full matrix, here is the one-line model: an **editor** does everything
across the feature surface **except** access-control administration and a small
set of admin-only deployment and infrastructure actions; a **viewer** sees that
same surface read-only; and both always keep self-service over their own
credentials.

> [!NOTE]
>
> **Admin-only means deployment-level.** A handful of genuinely dangerous,
> infrastructure actions are reserved for an admin and are **never** grantable to a
> non-admin role. Everything else — the day-to-day feature-configuration surface —
> an editor reaches through its **role grants** (a per-tag `read` / `write` level),
> because an editor is trusted to build and run the features it is granted.

The two columns below are independent lists — the left is the admin-only set, the
right is what an editor drives through its grants:

| Admin-only (never grantable) | Editor — via role grants (per-tag read / write) |
| - | - |
| Install / remove plugins (marketplace) | Hooks |
| Backup import / export | Presets and schedules |
| Write config and environment | Connectors |
| Read the deployment env / settings store — it holds deployment secrets such as the connector encryption key | Async tool runs |
| Role and policy administration | MCP config and sub-MCP mounts |
| Fleet / tool reloads, manifest replace, MCP-server registration and deregistration | Tool extensions, and reading the config mode |

A **viewer** reaches that same editor surface at `read` only. Both an editor and a
viewer always keep **self-service** — their own API keys, their own identity, and
their own password.

## Identity types

There are seven actors. Each is distinguished by **how it authenticates** and
**whether it is an admin** — the admin verdict is a condition-free `*` effective
policy, computed server-side and stamped on the request, never taken from a
provider's word.

| Identity | Admin? | Authenticates via | What it reaches |
| - | - | - | - |
| **Owner** | Admin | `POST /api/setup` → owner key | The first admin, created once by the setup door. Holds an admin key and, when an accounts provider is configured, an interactive login. |
| **Admin account** | Admin | password → session | A human on the reserved `admin` role — full reach, including access-control administration and every path, mapped or not. Its per-tag pass is skipped. |
| **Editor account** | Non-admin | session token | A human on the `editor` role: `write` on every grantable feature group, plus self-service. Everything except the admin-only fence and access-control administration. |
| **Viewer account** | Non-admin | session token | A human on the `viewer` role: `read` on every grantable feature group, plus self-service. Read-only over the same surface. |
| **Owned API key** | Non-admin | `sk-…` bearer / `X-Api-Key` | A key a user minted. It inherits its **owner's live role** — the owner's base-tier ceiling and per-tag grant map, re-applied each request — and its scopes are intersected with the owner's, isolated to its own runs / interactions / notifications. It cannot mint keys. |
| **Service principal's key** | Non-admin | `sk-…` bearer | A key an admin minted for a non-human **service principal**. Reaches exactly the routes its scopes map to — the one identity the route→scope table meaningfully gates. |
| **Unauthenticated** | Public | — none — | No credential. Reaches only public routes: the `/api/login` sign-in surface, anything declared or pinned public (a health or readiness probe), and the dataless Studio SPA shell. |

## The three composed layers

A role composes three parts, and enforcement is their **intersection**,
fail-closed:

1. **A base-tier ceiling** (non-editable) — owner-scoping for a minted key, the
   reserved `/api/auth` control-plane gate, and the viewer read-only ceiling.
   This is the security posture a role inherits from its tier (`admin`,
   `editor`, or `viewer`); it is never authored through the grant map.
2. **A route action-class** (declared at registration) — every authed route
   declares one of `read`, `write`, `fenced`, or `secret`. `read`/`write` are the
   **grantable** classes; `fenced`/`secret` are the admin-only fence. A route that
   declares no class fails boot — there is no allow-by-omission.
3. **A per-tag access-level map** (editable) — the role's level on each feature
   group: `none`, `read`, or `write`. This is the part an admin edits.

The action a request needs is derived from its HTTP method centrally —
`GET`/`HEAD`/`OPTIONS` → `read`, `POST`/`PUT`/`PATCH`/`DELETE` → `write` — so the
same route classes read and write uniformly.

## Permissions matrix

Rows are feature areas; columns are the identity types. Every cell reads against
the current seeded roles. The cell words mean:

| Cell | Meaning |
| - | - |
| `Full` | read + write, including admin-only ops |
| `Write` | the tag at level `write` — its reads and its non-fenced writes |
| `Read` | the tag at level `read` — GET / HEAD / OPTIONS only |
| `own only` | confined to the caller's own isolated slice |
| `by role` | owned key: reaches a feature exactly where its **owner's live role** allows, intersected with the owner's scopes |
| `by scope` | scoped key: reaches a route only where the route→scope table maps it to a scope it holds |
| `admin-only` | admin only, never grantable to a non-admin role — a `fenced` mutation, a `secret` read, or a `/api/auth` control-plane route held admin-only by the base-tier ceiling |
| `self` | the self-service surface only (own keys, own identity, own password, logout) |
| `—` | denied |

| Feature area | Admin | Editor | Viewer | Owned key | Scoped key | Unauth |
| - | - | - | - | - | - | - |
| **Agents** | Full | Write | Read | by role | by scope | — |
| **Presets / Templates / Tool extensions** | Full | Write | Read | by role | by scope | — |
| **Connectors** | Full | Write | Read | by role | by scope | — |
| **Storage & resources** | Full | Write | Read | by role | by scope | — |
| **Scheduling** | Full | Write | Read | by role | by scope | — |
| **Tool runs** (async execution) | Full | Write | Read | own only | by scope | — |
| **Interactions / Notifications** | Full | Write | Read | own only | by scope | — |
| **MCP config & status** (set config, reload a server) | Full | Write | Read | by role | by scope | — |
| **Sub-MCP mounts** | Full | Write | Read | by role | by scope | — |
| **Hooks** (register, topic verifiers) | Full | Write | Read | by role | by scope | — |
| **Tools** (inspect — list, tags, schema) | Full | Read | Read | by role | by scope | — |
| **Config mode** (`GET /api/config/mode`) | Full | Read | Read | by role | by scope | — |
| **Observability / Metrics / Health** | Full | Read | Read | by role | by scope | if public |
| **Manifest** (read) | Full | Read | Read | by role | by scope | — |
| **Fleet & workers** (read) | Full | Read | Read | by role | by scope | — |
| **Channels** (read) | Full | Read | Read | by role | by scope | — |
| **Marketplace** (browse) | Full | Read | Read | by role | by scope | — |
| **Backup** (list / read) | Full | Read | Read | by role | by scope | — |
| **Studio plugins · System kinds** | Full | Read | Read | by role | by scope | — |
| **Admin-only fence — never grantable** | | | | | | |
| **Run a tool directly** (`POST /api/run-tool`) | Full | admin-only | admin-only | by role | admin-only | — |
| **Reload / remove a tool** (`/api/tools/reload`, `/remove`) | Full | admin-only | admin-only | by role | admin-only | — |
| **Config env write + reload** (`POST /api/config/env`, `/api/config/reload`) | Full | admin-only | admin-only | by role | admin-only | — |
| **Replace the manifest** (`POST /api/manifest/replace`) | Full | admin-only | admin-only | by role | admin-only | — |
| **Reload-failed / deregister an MCP** (`/api/mcp-status/reload-failed`, `/{title}/deregister`) | Full | admin-only | admin-only | by role | admin-only | — |
| **Fleet reload** (`POST /api/fleet/reload-config`) | Full | admin-only | admin-only | by role | admin-only | — |
| **Marketplace install / uninstall / update** | Full | admin-only | admin-only | by role | admin-only | — |
| **Backup import / export** (`/api/backup/import`, `/export`) | Full | admin-only | admin-only | by role | admin-only | — |
| **Role & policy administration** (create / edit / delete / roll back roles, roll back a user's policy) | Full | admin-only | admin-only | by role | admin-only | — |
| **Admin-only secret reads — never grantable** | | | | | | |
| **Bulk role / policy reads** (`GET /api/auth/roles`, role version histories, a user's policy version history) | Full | admin-only | admin-only | by role | admin-only | — |
| **Deployment config reads** (`GET /api/config/env`, `GET /api/config/settings-schema`) | Full | admin-only | admin-only | by role | admin-only | — |
| **Control-plane routes (`/api/auth`) — admin-only via the base-tier ceiling, not the fence** | | | | | | |
| **Scopes, route table, public-route pins** (`/api/auth/scopes*`, `GET /api/auth/routes`, `/api/auth/public-routes`) | Full | admin-only | admin-only | by role | admin-only | — |
| **Self-service — always allowed** | | | | | | |
| **Own API keys + claim links** (`/api/auth/api-keys`, own) | Full | self | self | no mint | by scope | — |
| **Own identity + password + logout** (`/api/auth/me`, `capabilities`, `users/me/password`, `logout`, `GET scopes`) | Full | self | self | self | by scope | — |
| **Login / claim exchange** (`/api/login`, public) | public | public | public | public | public | public |

**`by role`** — an owned key reaches a feature exactly where its **owner's live
role** allows, intersected with the owner's scopes and re-evaluated on every
request. There is no per-key grant map: a key follows its owner's role up and
down as an admin edits it. Isolation to the caller's **own** runs, interactions,
and notifications is the only hard resource confinement.

### The grantable per-tag surface

The **resource** is a feature group (a route's tag); the **action** is derived
from the HTTP method — the same shape as Kubernetes RBAC, AWS IAM, or GitHub
fine-grained permissions. A role's level on a tag decides its reach:

* `write` admits the tag's reads **and** its non-fenced writes;
* `read` admits the tag's reads only (GET / HEAD / OPTIONS);
* `none` (the default for any tag not in the map) admits nothing.

A role granted a tag reaches every grantable route under it — including a route
added later under that same tag. Shipping a **brand-new** feature group is a
deliberate release step: its tag is level `none` for every non-admin role until
an admin grants it. The seeded `editor` and `viewer` roles derive their maps from
the live route registry, so a new grantable feature area joins their default
reach automatically; a role an operator authored does not, and an admin opens it
explicitly.

### The admin-only fence

Two route action-classes are **never grantable** — no per-tag level opens them
for any non-admin role. They cover the infrastructure mutations, the
role and policy control plane, and the deployment's env/settings store — not the
everyday feature-configuration surface an editor drives through each feature's own
routes:

* **`fenced`** — the admin-only mutations. Running a tool **directly**
  (`POST /api/run-tool`); reloading or removing a tool; writing and reloading
  config (`POST /api/config/env`, `/api/config/reload`); replacing the manifest;
  reloading failed MCPs and deregistering an MCP; reloading the fleet; marketplace
  install / uninstall / update; backup import / export; and the role and policy
  control plane — creating, editing, deleting, and rolling back roles, and rolling
  back a user's policy. Editing scopes, the route table, and the public-route pins
  is **not** `fenced` — those routes are ordinary `read`/`write` class, held
  admin-only by the base-tier `/api/auth` control-plane ceiling described below.
* **`secret`** — the admin-only reads, over two admin-owned stores. The **bulk
  role / policy reads**: the roles listing (`GET /api/auth/roles`), the role
  version histories, and a user's policy version history — their payload carries
  raw jq policy bodies, so a bulk read is admin-equivalent. And the **deployment
  config store**: the stored environment (`GET /api/config/env`) and the
  per-settings-class values (`GET /api/config/settings-schema`). Environment and
  settings are one store — the deployment's environment plus each settings class's
  values, including deployment secrets such as the connector encryption key — so
  only an admin reads or writes it.

Because the class is **declared on the route**, the fence is not a
hand-maintained list an author can forget to extend: a new mutating route that
should be admin-only declares `fenced`, and a route that declares nothing fails
boot rather than defaulting open.

> [!NOTE]
>
> **An editor configures every feature; it does not own the deployment store.** An
> editor keeps **full feature functionality** — it configures connectors, MCP and
> sub-MCP config, presets, hooks, schedules, and tool extensions through each
> feature's **own** grantable routes and stores, never through the env/settings
> store. Running a tool through the **async** run surface (`POST /api/tool-runs`),
> scheduling a tool, setting the MCP config, reloading a single MCP server, mounting
> a sub-MCP, setting tool extensions, registering hooks, and reading the hooks
> listing are ordinary grantable `read`/`write` routes an editor reaches. What stays
> admin-only is the deployment config store — reading the env and settings
> (`GET /api/config/env`, `GET /api/config/settings-schema`) and the env write —
> alongside the pre-existing infrastructure mutations (a **direct** tool run, tool
> reload / remove, fleet reload, manifest replace, MCP reload-failed / deregister,
> marketplace, backup) and access-control administration.

### The control-plane (`/api/auth`) gate

The `editor` and `viewer` base tiers **default-deny the whole `/api/auth` area**
and carve back in only a fixed **self-service** list: managing one's own API keys
and claim links, the identity projection (`me`, `capabilities`, `tokens-payload`,
the read-only `GET /api/auth/scopes`), changing one's own password, and logout.
Everything else under `/api/auth` — editing scopes, the route table,
public-route pins, policy history and rollback, and role and account management —
falls to the default-deny, so only an admin reaches it. This ceiling is separate
from the action-class fence, and it holds even for a viewer: the self-service
surface stays reachable regardless of the read-only ceiling.

## How a request is judged

The verdict composes the layers with **AND**, evaluated **fail-closed** — a
backend error at any layer raises and surfaces as a clean deny, never a silent
default.

**1. Authenticate and resolve the role**

The credential resolves to an identity and its policy. The policy carries a
live **role-name pointer**, not a frozen copy — enforcement reads the role's
**current** grant map at request time. For an **owned key**, the governing
role is the **owner's**, and the key's scopes are intersected with the
owner's right here, so a change to the owner takes effect on the key's next
call.

**2. The base-tier ceiling**

The role's base-tier condition applies: owner-scoping, the `/api/auth`
control-plane gate, and — for a viewer — the read-only ceiling. An **admin**
is condition-free and skips this pass.

**3. The per-tag level + the fence**

The request's route resolves to its feature tags and action-class. A
`fenced` or `secret` route denies every non-admin outright. Otherwise the
governing role's level on the route's tag must satisfy the method's derived
action. An admin skips this pass entirely.

**4. The route→scope table**

The request path maps to scope ids, and the guard admits the request only if
the identity's scopes cover **every** one. Because every role-holder carries
`*`, this gate only meaningfully constrains **scoped keys**: a registered,
authenticated route the operator mapped to no scope resolves to the universal
scope `*`, so every role-holder reaches it out of the box while a scoped key
needs an explicit row. A path the application does **not serve** (no registered
route) resolves to nothing and **fails closed** for every ordinary identity —
the sole exception is the stamped super-admin, admitted so a root can never
lock itself out of a route it can map anyway.

An authentication failure returns a fixed `401`; an authenticated-but-forbidden
request returns a fixed `403`. The full reason is logged server-side only.

## Roles are live and editable

A role is not a fixed template. An admin can **create, edit, delete, and roll
back** roles — through the Studio or the [`tai roles`](/reference/cli/roles) CLI —
and every edit is **live**: it changes every current holder's authorization on
their next request, with no reassignment. Editing a role also re-attenuates every
key its holders own, since an owned key follows its owner's live role. The
reserved `admin` role is permanent — undeletable, unrenamable, always full
control — and **multiple admins are allowed**. See [accounts](/concepts/accounts#roles)
for the editing surface and the assignment flow.

## The last enabled admin stays

An **admin** is every enabled principal whose own policy is admin-shaped — an
account on the `admin` role, the owner the setup door creates, a service principal
on the `admin` role — whichever provider or door created it. The platform refuses
any change that would leave none (`409`, nothing written), on every door that can
change a principal's standing:

* a member action that changes a role, disables, or removes an account;
* disabling or deleting a principal through the principals routes;
* editing a principal's own policy through the API-key routes — its scopes or its
  condition — or rolling that policy back to an earlier version.

A principal's `disabled` state lives on its principal record and is mirrored into
its policy data (`"disabled": true`) for enforcement. Only the principals routes, the
member actions, and an [`access_control` restore](/operate/backup-and-restore) change it — a
restore gives a principal the deployment does not hold yet its archived state, and leaves an
existing principal as it stands. A policy edit or rollback never does. An edit whose
policy data carries a `disabled` value other than the principal's current state
(`true` while disabled, `false` while enabled) is refused (`400`, nothing written);
any other edit, and every rollback, keeps the principal's current state. Minting an
API key whose policy data carries `disabled` is refused the same way: an API key is
switched off by revoking it.

Deleting a scope or a route never reaches an admin's grant: the universal scope
`*` names no route, so mapping a route to it (`POST /api/auth/scopes` with
`"scope_id": "*"`) and deleting it (`DELETE /api/auth/scopes/*`) are both refused
(`400`, nothing written). Mapping a URL into any scope is refused the same way when a
route that declares itself public serves it, on any method: such a route answers
everyone whatever it is mapped to, and the routes listing marks it
`declared_public: true`.

A policy that grants nothing is never written either. A policy with neither a scope
nor a condition reads as no key at every door, so minting an API key with neither is
refused (`400`, nothing written), and so is an edit that would leave a key's or a
principal's own policy with neither — the refusal says to revoke the key, or to disable
or delete the principal. For the last enabled admin principal the last-admin `409`
answers first.

Because every admin counts, demoting the last admin **account** is allowed while
another admin principal — the owner, say — is still enabled. Promoting someone
never needs the check, and an API key's own policy row is not a principal and
never counts. Nor can it become one: creating a principal under the user id of a
minted key (`POST /api/auth/principals`) is refused (`409`, nothing kept).

## An account is not an API key

Two things are easy to confuse because both hand someone a working identity. They
are **different in kind** — who creates them, what sets their authority, and how
far that authority reaches.

| | **Account (user)** | **API key** |
| - | - | - |
| What it is | A human login | A scoped credential |
| Who creates it | Only an **admin** | **Any** user, for itself |
| Where its authority comes from | The **role** an admin assigns it | Its own scopes, **capped by its creator** |
| How far it reaches | Whatever its role grants | Never more than its creator — an owner-attenuated slice |
| Reassignment | An admin moves it to a different role | Its ceiling follows its owner's live role automatically |

An **account** is the human side: only an admin creates one, and its authority is
the [role](/concepts/accounts#roles) the admin assigns by name. The account's
enforced policy carries a **live pointer** to that role, not a copy — editing the
role changes the account's access on its next request, and moving the account to a
different role re-points it immediately.

An **API key** is a credential **any** user mints to delegate a slice of its
**own** access to a teammate, a device, or a script. A key minted by a non-admin
is an [owned key](/concepts/owned-keys): **attenuated** to a subset of its
creator's authority, **capped live** (the cap is re-applied every request, so it
follows the owner up and down), and **isolated** to its own slice of the runs,
interactions, and notifications surfaces. A key can never exceed the user who
created it, and an owned key can never itself mint further keys. Editing an
account's role therefore also re-attenuates every key that account owns, without
touching the keys themselves.

## See also

* [Access control](/concepts/access-control) — the request gate, scopes, and the jq policy model.
* [Owned keys](/concepts/owned-keys) — capped sub-identities, attenuation, and data isolation.
* [Accounts](/concepts/accounts) — human accounts, sessions, and the editable role model.
* [Set up access control](/guides/access-control) — turn on the gate and write a policy.
* [`tai roles`](/reference/cli/roles) — create, edit, and roll back roles from the terminal.
* [HTTP API reference](/reference/api/index) — the routes behind each surface.


# Presets
Source: https://docs.tai42.ai/concepts/presets

Versioned, named wraps of a tool.

A preset is a base tool with a partial set of keyword arguments baked in, exposed
as a new named tool. It lets you save a configured variant of a tool once and call
it by name, and it rides the platform's [versioning spine](/concepts/versioning-spine)
so the configuration can evolve without breaking callers.

A preset's organizational metadata — a display name, a folder, user tags, and
visibility — is not part of the preset record; like any tool, a preset carries it
in the unversioned [tool-organization overlay](/concepts/tool-organization),
keyed by its tool name.

## The bind kernel

At the centre of the feature is a bind kernel that builds the live tool: it takes
a base tool and fixes some of its arguments, producing a hidden transform of the
original. The baked values fill in behind the scenes, so a caller supplies only
the arguments that were left open. The base tool is any registered tool —
including a management [operation](/concepts/live-operations) projected as a tool,
so you can save a configured variant of a live-ops action just as you would any
other tool.

## The store view

A preset persists through a typed store view over the platform's generic
versioned-document store, tagged `kind="preset"`. **Every preset is a versioned,
store-backed record** — there is one tier, not two. Create writes a durable store
row and then registers the live tool; every save appends a new version, one version
is active, and you can roll back to an earlier one. A preset always rides the
[versioning spine](/concepts/versioning-spine).

The contract owns the `PresetStore` protocol and the `PresetBody` model; the
skeleton owns the concrete view and the bind kernel.

## Across the fleet

A preset mutation lands locally — the store write plus the live rebind — and then
broadcasts on the [worker bus](/concepts/worker-bus) so every worker sharing the
manifest re-reads the active body and rebinds. In a single-process deployment the
local apply is the whole fleet. The store write and the local rebind have already
landed by the time the broadcast runs, so the response is the plain preset record;
a preset broadcast that does not converge is not embedded in that response but
surfaced server-side as a loud non-convergence ERROR log that names the workers the
change did not reach — `departed`, `timed_out`, or `missing`. Re-run the mutation,
or a fleet `reload_config`, to reconverge the named workers.

## Conflicted records

A preset whose stored body can no longer bind — its base tool or an extension it
names was removed since it was authored — is **quarantined** rather than dropped.
It stays visible in the listing with `conflicted: true` and a human-readable
`conflicted_reason` explaining the cause (`null` when the record is healthy). A
conflicted record is **delete-only**: save-version, rollback, and rename all reject
it with a `409`, and only `delete` clears it (a hard store removal that touches no
registration). This field is the only place the cause is reported — resolve a
conflict by deleting the record and re-creating it once its base is back.

## Plugin-shipped defaults

Beyond the tools, extensions, and agents a [plugin](/concepts/marketplace) can
carry, a plugin may also ship **default presets** — preset definitions it declares
in code, which the platform seeds at boot. A declared default is created when it is
absent and upgraded in place when the plugin's shipped definition changes across
releases, so a fresh install and an upgrade both land the current default without
any operator step. The seeding is one-directional and deferential: a seeded default
stays plugin-owned only while it is untouched, and the first time an operator edits
it the preset becomes operator-owned and the plugin never overwrites it again. A
seed likewise fills a default's display name, tags, or folder only where the
[organization overlay](/concepts/tool-organization) leaves them unset, never over an
operator's own label.

## Baked values are a may-run boundary

A preset's baked `fixed_kwargs` are a *may-run* boundary, not a *may-read* one.
They are hidden from framework-manufactured surfaces — the tool input schema and
validation-error messages — so a caller authorized only to run the preset does not
see them through those channels.

Every preset read door — get a preset, get a version, list the versions, the MCP
read tool, and `tai presets show` / `tai presets versions` — masks any value baked
under a **secret-typed parameter** of the base tool: a leaf the base tool's input
schema types as a `SecretStr`, a `format: password` string, or a write-only field.
A literal baked under a **non-secret** parameter is returned as authored, so the
may-run caveat below still stands for non-secret sensitive config. An `!ENV` marker
is left verbatim — it is a [reference](#secret-references-in-baked-kwargs), not a
stored credential — and the backup export stays verbatim. When the base tool cannot
be resolved (its plugin is absent), the read fails closed and masks every baked
value.

> [!WARNING]
>
> A literal baked value is present in the running tool's context and may appear in
> anything the tool or an agent emits — output, tool-call arguments, traces, error
> text — which the framework cannot generically scrub. Never bake a raw credential
> as a literal; bake a [secret reference](#secret-references-in-baked-kwargs)
> instead. If the baked config is sensitive, treat run authorization as "may run",
> not "may read the config".

## Secret references in baked kwargs

A `fixed_kwargs` string value written `!ENV ${VAR}` is a **secret reference**, not a
stored credential. It is the same `!ENV` marker a manifest value and a Studio secret
field carry — [referenced, not embedded](/concepts/config-and-secrets#secrets-are-referenced-not-embedded)
— sitting at a baked kwarg:

```yaml examples/presets/secret_reference_preset.yaml theme={null}
# A preset that bakes a secret REFERENCE, not a credential: the `!ENV ${VAR}`
# value is kept verbatim in the store and resolved from the environment at bind.
base_tool: echo_tool
description: A configured variant that carries a service token as a reference.
fixed_kwargs:
  api_token: "!ENV ${SERVICE_API_TOKEN}"
```

The store keeps the marker verbatim. Every read, list, version, and backup export
returns the reference string, never a value — the credential was never stored, so
nothing there needs masking. A caller with "may read the config" sees
`!ENV ${SERVICE_API_TOKEN}`, not the token.

The bind kernel resolves each reference once, from the server's environment, as it
builds the live tool: it reads `VAR` and bakes the value wrapped so the framework
masks it wherever a run is recorded — traces, results, error text. The resolved
value reaches only the base tool's own call, never a stored surface.

A reference may sit anywhere in a baked value — a top-level kwarg, a list element, a
field of a nested object, or a dictionary value. The bind kernel walks the base
tool's own input schema alongside the baked kwargs and reveals the resolved value to the
tool by the tool argument binding rule
([a wrapped value as a tool argument](/concepts/secret-values#a-wrapped-value-as-a-tool-argument)):
revealed wherever the schema types that position with a concrete leaf type (a `str` field, a
`list[str]` element, a typed model field, a `dict[str, str]` value, a union whose every branch
is typed), and kept wrapped — masked wherever the run is recorded — wherever the schema leaves
the position open.

An unset referenced variable never binds silently. A write that references a
variable the server does not have fails loudly with a `400` naming the variable and
the kwarg, and a stored preset whose variable is absent at boot is
[quarantined](#conflicted-records) rather than bound empty, with the missing
variable named in the boot log.

A reference may carry a default — `!ENV ${VAR:fallback}` — used when the variable is
absent. A default is opt-in non-secret config: it is stored, versioned, and exported
in the clear like any other baked value, so never write a credential as a default.

In the Studio, the create-preset and save-version dialogs author these references as
typed rows that pick an existing environment key — see the
[fixed kwargs editor](/studio/presets#the-fixed-kwargs-editor).

## Managing presets

Create, version, roll back, and rename presets from the CLI:

```bash theme={null}
tai presets list
tai presets versions <name>
tai presets rollback <name> <version>
```

Beyond the create/version/rollback core, the surface carries four more doors:

* **`validate`** — a dry-run that reports whether a draft would be accepted,
  running the exact pre-write checks the create (new name) or save-version
  (existing name) route runs, without writing anything. A malformed request is a
  `400`; a valid or invalid draft is both a `200` carrying a `valid` verdict.
* **`referees`** — every live reference a rename of this name would strand, listed
  so a UI (or you) can preflight the rename. The list is the full union: the other
  presets whose authored-agent composition names this one as a tool, **plus every
  behavioral holder that wires against the name** — a schedule that fires it, a hook
  that targets it, a conversation route pointing at it, a tool-extensions map entry
  carrying it, a parked interaction whose resume continuation is it, and any
  plugin-held reference a plugin declares through the rename-referee seam. Each
  holder is named individually.
* **`rename`** — a preset's name *is* its live tool name, so a rename rebinds the
  tool (new name bound before the old is torn down). Rename integrity is enforced
  atomically **at this one gate**: it runs create's name pre-checks on the new name
  and **blocks with a `409` listing every holder** — the same full referee union
  above (referencing presets and behavioral wiring alike) — so you update those
  references first rather than have the rename silently strand them. It also rejects
  a conflicted record (`409`) and a no-op rename (`400`). Display metadata is not a
  behavioral reference: a tool's [organization overlay](/concepts/tool-organization)
  follows the name across a rename rather than blocking it.
* **`set-version-tags`** — replace one version's `tags` annotation. Tags are
  labels on an immutable version body, so this never rebinds the live tool.

## Per-base-tool write validators

Those "pre-write checks" are extensible per base tool. A base-tool plugin can
register a validator against its own `base_tool` name so that every preset written
over it is checked before it persists — the pinning preset for the
[external-confirmation ask](/guides/use-interactions#the-pinning-preset-is-required-not-optional),
for instance, is the kind of constraint such a validator can enforce.

A plugin registers one when its tool module loads:

```python theme={null}
from tai42_contract.app import tai42_app

tai42_app.presets.register_write_validator("request_confirmation_ask_external", my_validator)
```

The preset write path consults the validator registered for a body's `base_tool`
on **every** write — create, save-version, and rollback — and the `validate`
dry-run door runs the same check without persisting. The registry is rebuilt on
each `start()`, so a reload re-imports the tool modules and re-registers cleanly;
registering the same `base_tool` twice within one load raises loudly rather than
silently swapping a base tool's write gate.

## Declarable per-tool input schema

A preset can declare the exposed named tool's own typed input schema **when its
base tool supports one** — a base tool registers support for it at load, the same
`register_*`-at-load pattern as a write validator. When it does, the bind kernel
routes the caller's validated object into the base tool's invocation. Most base
tools declare no support: their typed schema is fixed. The shipped one that does
is `sandbox_exec` — see the
[sandbox concept](/concepts/sandbox#running-code-as-a-named-tool).

The declared `input_schema` is part of the **versioned body**, not a create-only
field: it is set at create and **updated through the save-version door** just like
the baked kwargs, so a schema change is a new version you can roll back to an earlier
one.

When a preset bakes the base tool's **payload argument itself**, that baked object is
treated as a set of partial **defaults** rather than an absolute constant: the
caller's validated object **deep-merges over** it, caller-wins-per-key — nested
objects merge recursively, while a list or scalar the caller supplies replaces the
baked one (lists never concatenate). So a preset can pin default fields while still
letting a caller override any of them. Every other baked kwarg stays a fixed, hidden
constant.

## State binding on a version

A preset version's body may carry a
[`state_binding`](/concepts/states#a-bindings-subject-and-scope) — the door-side binding that
injects an `input`-purpose template jq's value before the tool runs and applies an
`update`-purpose op batch after it. The binding is **part of the versioned body**, so it is
validated and attached on **every** write — create, save-version, and rollback alike. A rollback
is not a bare re-point: it validates and attaches the target version's binding exactly as create
and save-version do. Attaching is attach-on-use and idempotent, so a template that was merely
**detached** since the version was authored — but whose document still exists — is re-attached
automatically and the rollback succeeds. The rollback is refused and nothing is re-pointed
only when the named template **document** no longer exists (it was deleted, a `404`) or its
attach path is occupied (a `409`) — re-create the template document first (a merely detached
template needs nothing). A save-version that carries the binding forward attaches nothing: the
carried binding was checked at its own save. The statuses every binding refusal answers are
listed under [saving a binding](/concepts/states#saving-a-binding).

## Admin registration tier

A base tool can declare the authorization tier that fences it. Declaring the admin
`fenced` (or `secret`) tier gates both **authoring** a preset over the base tool —
enforced at the shared preset chokepoint on every authoring door — and **running**
it, so a preset authored over a fenced base inherits the fence at run time. The
default stays the presets' own `write` for a base tool with no declaration;
`sandbox_exec` declares `fenced`, because registering and running a runnable code
tool is an admin act. See [fenced tools](/guides/build-a-tool#fenced-tools) and the
[sandbox concept](/concepts/sandbox#running-code-as-a-named-tool).

See the [create-and-version-a-preset guide](/guides/create-and-version-a-preset)
for the full workflow, the [versioning spine](/concepts/versioning-spine) for the
store presets ride on, and the [CLI reference](/reference/cli/index) for the
complete `tai presets` command set.


# Private tool sets
Source: https://docs.tai42.ai/concepts/private-tool-sets

Scoped sub-MCP servers.

A private tool set is a sub-MCP server mounted inside a running server. It exposes
a chosen subset of tools under its own slug and its own MCP endpoint, so one server
can present several scoped surfaces instead of one flat catalog.

This page explains the model. To register one, follow
[Expose a private tool set](/guides/private-tool-set).

## Sub-MCP apps

A sub-MCP app is registered on the live sub-app router under a slug, listing the
tools it exposes and the transport it serves. Each registration is a self-contained
MCP surface: a client that connects to a sub-MCP sees only that set of tools, not
the whole server. The registry keeps a JSON-safe view of every registered sub-MCP —
its slug, its tools, and its transport.

## Registering and tearing down

Sub-MCP apps are managed live, at run time, through three authed doors and their
CLI commands:

```bash theme={null}
tai sub-mcp list
tai sub-mcp register utilities --tool convert --tool lookup   # register or reload a slug with its tool set
```

Registering a slug builds (or reloads) its sub-MCP app; unregistering it tears down
the sub-app's ASGI lifespan cleanly. An unknown slug fails loudly with a `404`
rather than silently succeeding. The
[Studio Served endpoints screen](/studio/screens#served-endpoints) drives the same
doors — listing each slug with its transport and `/app/{slug}` connect URL, and
creating or removing one in place.

## Why scope a tool set

A private tool set narrows what a given client can see and call. Pairing a sub-MCP
with [access control](/concepts/access-control) lets you route different callers to
different scoped surfaces of the same server, keeping each client's tool list
minimal and intentional.

> [!NOTE]
>
> The sub-MCP namespace is `app.sub_app`. It is separate from the raw FastMCP escape
> hatch on the [MCP-citizen surface](/concepts/mcp-citizen-surface), which is named
> `app.fastmcp` precisely so it does not read as the sub-MCP.

See the [private-tool-set guide](/guides/private-tool-set) for exposing one and the
[HTTP API reference](/reference/api/index) for the `/api/sub-mcp` routes.


# Sandbox
Source: https://docs.tai42.ai/concepts/sandbox

An isolated execution session any plugin can request: workspace, exec, file transfer, and a reap deadline.

A sandbox is an execution session a plugin requests when it needs to run code
away from the server process. A session carries a workspace volume, `exec` (both
one-shot and interactive), file transfer in and out, and a TTL reap deadline.
How strongly a session is isolated depends on the provider. It is generic and
optional, exactly like a [backend](/concepts/backends): a deployment without a
provider carries nothing for it.

## The sandbox seam

The `Sandbox` ABC is the contract. A consumer acquires a session through the one
raising chokepoint `tai42_app.sandboxes.require_sandbox()` — every door that runs
code flows through it, so a single seam owns the policy. An external plugin
registers a provider through `tai42_app.sandboxes.register_sandbox` when the
[manifest](/concepts/manifest) names the `sandbox_module`.

With no provider installed the kind row reads `off`, and any consumer that calls
`require_sandbox()` gets a loud typed `SandboxUnavailableError` naming
`TAI_MCP_SANDBOX` and the `sandbox_module` — surfaced through that consumer's own
error path, never a silent no-op.

## Two providers, one execution mode

The `sandbox` slot is a scalar single holder: a deployment installs exactly one
provider, and which one is installed **is** the execution mode. The consuming
agents keep one code path either way.

* `sandbox-docker` runs each session as an **isolated container**.
* `sandbox-local` runs the code **directly on the host** — the workspace is a
  host directory, with **no isolation**.

Isolation is a contract Literal, `SandboxIsolation = "none" | "container" | "vm"`,
with floor semantics (`none < container < vm`). The operator's
`sandbox_isolation` sets the floor (default `container`); a session spec's
`isolation` field requests at least a level (`None` inherits the floor); and a
provider must give **at least** the effective level or reject the spec.
`sandbox-docker` satisfies `none` and `container` and rejects `vm`;
`sandbox-local` satisfies `none` only and rejects `container` and `vm`. Put
plainly: `sandbox-local` is the no-isolation, direct-on-the-host provider.

See [operate/sandbox](/operate/sandbox) for installing and wiring a provider.

## Durability

Durability is one tier on the session spec: `durability: "ephemeral" |
"persistent"`. An ephemeral session's workspace dies with the session. A
persistent session binds a durable workspace volume (`tai-sbx-<workspace_key>`)
provisioned at the distribution layer — a PVC on Kubernetes, a named volume in
Compose — that survives the session and its reap.

There is no platform "git tier": taking data off-box for backup is a consumer's
own action with its own credentials. The deployment side of durability lives on
[operate/sandbox](/operate/sandbox).

## Security is configuration

A session is trusted with exactly the credentials and the reach the operator
grants it. Security is the per-consumer credentials list plus four platform
settings, all enforced once at the session-create chokepoint every consumer
flows through — both agents and `sandbox_exec` — so no door bypasses the policy:

| Setting | Env | What it sets |
| - | - | - |
| `sandbox_egress` | `TAI_MCP_SANDBOX_EGRESS` | the egress ceiling (default open) |
| `sandbox_isolation` | `TAI_MCP_SANDBOX_ISOLATION` | the isolation floor (default `container`) |
| `sandbox_scrub_transcript` | `TAI_MCP_SANDBOX_SCRUB_TRANSCRIPT` | transcript scrub (off by default) |
| `sandbox_durable` | `TAI_MCP_SANDBOX_DURABLE` | durable persistent workspaces on or off |

> [!WARNING]
>
> Under the default open egress, any data a session can read is exfiltratable — so
> a session is trusted with exactly the credentials and reach the operator grants
> it. Under `sandbox-local` there is no isolation at all: the code runs on the host.
> Tighten `sandbox_egress` and choose the provider deliberately.

## Consumers

The sandbox's consumers in this release live in the base tool and the ready-made
agents package:

* the [`sandbox_exec` code tool](/concepts/sandbox#running-code-as-a-named-tool)
  (below), a generic base tool that runs a command in a session;
* ready-made [agents](/concepts/agents) that reach the same seam two ways — one
  drives an external code runtime inside a session, the other's durable scratch
  filesystem **is** a sandbox backend over the same seam. See
  [the agents plugin](/plugins/tai42/agents) and
  [the guide](/guides/use-the-ready-made-agents).

The generic seam enables wider consumers not shipped here: any agent execution
backend, a generic code-execution tool beyond `sandbox_exec`, isolation for
stdio MCP servers, and skills that bundle executable scripts.

## Running code as a named tool (`sandbox_exec`)

`sandbox_exec` is a generic base tool that ships in the skeleton. It runs a
command in a sandbox session acquired through `require_sandbox()`, with a durable
workspace when the preset asks for one. It is domain-agnostic: a delivery turns
concrete named tools into [presets](/concepts/presets) over it.

Two generic preset mechanisms make that possible, both consulted at the shared
preset chokepoint so every authoring door is covered:

* **A declarable per-tool input schema** — a preset over a schema-accepting base
  tool declares the exposed named tool's own typed input contract, and the bind
  kernel routes the caller's validated object into the base tool's invocation.
  Most base tools accept none — their schema is fixed — but `sandbox_exec` does.
  See [presets](/concepts/presets#declarable-per-tool-input-schema).
* **An admin registration tier** — `sandbox_exec` declares the admin `fenced`
  tier, which fences both authoring a preset over it (the shared preset chokepoint,
  every authoring door: HTTP, MCP, CLI, manifest-apply) and running it (the shared
  tool-run chokepoint, every run door), never one route. A preset over it inherits
  the fence at run time. Registering and running a runnable code tool is an admin
  act. See [fenced tools](/guides/build-a-tool#fenced-tools) and
  [presets](/concepts/presets#admin-registration-tier).

> [!WARNING]
>
> The code a `sandbox_exec` preset runs holds the credentials the operator injects
> into the session and, under the default open egress, reaches the internet. That
> is deliberate — the delivery's own code is trusted with its own credentials — and
> it is why authoring one is admin-fenced.
>
> Contrast this with the adapter-proxied posture an
> [agent](/guides/use-the-ready-made-agents) gets: an agent's platform tools run
> **outside** the session under the run's own identity, with no credential or
> endpoint exposed to the code, whereas `sandbox_exec` code runs **inside** the
> session with the injected credentials in hand. Two deliberate trust models over
> one sandbox seam.

### Preset network portability across providers

A `sandbox_exec` preset with an explicit `network="none"` (or `"internal"`) runs
under `sandbox-docker` but is loudly rejected under `sandbox-local`, which honors
`network="egress"` only and raises `SandboxSpecRejectedError` on `none` or
`internal`. An unset `network` defaults to `"egress"` (the base tool's schema
default) and already runs under `sandbox-local` — so only a preset that
explicitly pins `none` or `internal` must be changed for a `sandbox-local`
deployment. The mismatch is a loud rejection at session create, never a silent
failure.

## See also

* [Backends](/concepts/backends) — the sister execution seam for queued work.
* [Presets](/concepts/presets) — the spine `sandbox_exec` named tools ride on.
* [operate/sandbox](/operate/sandbox) — install a provider and wire the engine.
* [Use the ready-made agents](/guides/use-the-ready-made-agents) — the shipped
  sandbox-driving agents.


# Secret values
Source: https://docs.tai42.ai/concepts/secret-values

Wrap a value a tool returns so it reveals once to a live caller and masks everywhere it is recorded.

Some tools return a value that must reach a live caller but must never be
written down — a signing secret a provider shows only once, a token, a password
a person just typed. The **secret-value envelope** carries such a value through
the platform so it is revealed exactly once, at the live edge that asked for it,
and shows a placeholder on every surface that records.

Where [config and secrets](/concepts/config-and-secrets) covers the secrets a
server *reads* (referenced by env-var name, never embedded), this page covers the
secrets a tool *produces* — the outbound half.

## The envelope

`SecretValue`, from `tai42_contract.secrets`, wraps a real value inside a tool's
return:

```python theme={null}
from tai42_contract.secrets import SecretValue

return {"endpoint_id": endpoint_id, "secret": SecretValue(raw_secret)}
```

The wrapper is deliberately hard to leak:

* **`reveal()` is the only way out.** `wrapped.reveal()` returns the real value;
  nothing else does.
* **Its text form is a placeholder.** `repr` and `str` both yield
  `SecretValue([secret])`, so it cannot leak through a log line or an f-string.
* **It is not JSON-serializable — on purpose.** Any un-audited path that tries to
  dump it raises `TypeError` and fails loudly, rather than quietly emitting the
  value. This fail-safe is what makes the wrapper safe to carry through code that
  was never told a secret is inside.
* **It compares and hashes by identity**, not by value, so equality checks and
  set membership cannot become a timing or logging trap.

## What each surface sees

The wrapper travels intact through the platform's shared tool-result seam. Each
door then decides for itself: a live edge reveals the real value once; every
recording masks it to the `[secret]` placeholder.

| Surface | What it gets |
| - | - |
| A live run-tool HTTP response | the real value, once |
| An MCP `tools/call` result | the real value, once |
| A [preset](/concepts/presets) wrapping such a tool | the real value, once |
| A model- or agent-visible tool result | `[secret]` |
| A run record, trace, or monitor span | `[secret]` |
| A detached run that stays in-process — a background submit, a hook or trigger fire | records `[secret]` |
| A run relocated to a backend worker — a scheduled run, a backend-worker task | fails loudly: the wrapper will not serialize |

The one handoff of a real secret is therefore a **live, synchronous call** — a
direct run-tool response, an MCP tool call, or a preset over one. A detached run
that still executes **in-process** — a background submit, a hook or trigger fire
— has no live caller to hand the value to, so it only records, and records the
placeholder. A run **relocated to a backend worker** — a scheduled run, a
backend-worker task — never reaches that in-process recorder: the wrapper does
not serialize onto the wire, so the run fails loudly rather than carry a secret
across the process boundary, by design. Plan a secret-producing tool to be
called synchronously by whoever consumes the value.

A model never sees a secret either: the adapter that feeds an agent's model,
checkpoint, and callback trace masks the wrapper before the result leaves it.

> [!NOTE]
>
> When a preset pins an [output schema](/concepts/presets) and a secret-bearing
> result violates it, the error keeps the failing JSON path but replaces the value
> with `[secret]`. The plaintext never rides a raised validation error into a log.

## A wrapped value as a tool argument

A tool validates its arguments against its own input schema before its body runs, and a
`SecretValue` is not a string. Tool argument binding therefore reveals a wrapped argument where
that validation would reject the wrapper: wherever the tool's schema types the position with a
concrete leaf type — a `str` field, a `list[str]` element, a typed model field, a
`dict[str, str]` value. A union counts as typed only when *every* branch is typed — `str | None`
is revealed, while `str | Any` or `str | object` keeps its permissive branch, so the value stays
wrapped. Wherever the schema leaves a position open — `Any` or `object`, or anything nested
beneath such a position — the value keeps its wrapper and is masked wherever the run is
recorded; a container under a permissive branch is left wholly wrapped, never descended into.
A [preset](/concepts/presets#secret-references-in-baked-kwargs)'s resolved secret references
reach the base tool by this rule.

## Sensitive questions

[`ask`](/concepts/interactions) can collect a secret from a human. Pass
`sensitive=True` and:

* the answer comes back **wrapped** in a `SecretValue`, so the tool reaches it
  only through `reveal()`;
* the durable question record keeps **only the answered status** — the answer
  body is never persisted;
* if the turn is killed on its timeout while a sensitive question is still
  pending, the timeout error names the interaction but shows
  `[sensitive question]` in place of the question text.

A synchronous `ask` returns an `AskAnswer` whose `answer` is that `SecretValue`, so a tool
that returns the `ask(..., sensitive=True)` result **directly** is refused when its result
is written (`UnencodableLeafError`: a `SecretValue` is never encoded). Return
`.answer` — the `SecretValue` itself, which the run masks — or a value you derived from
`reveal()`.

A reply quoting an answer to a sensitive question reads `status: "sensitive"` with no text:
the answer body is never kept, so there is nothing to quote.

The question **text**, though, is always visible wherever the question is
delivered and in the stored record. Never put a secret in the question itself —
ask *for* the secret, do not restate one.

## Author rules

* **Wrap at the return site.** Construct the `SecretValue` where the value is
  produced and put it straight into the return. One wrap protects the value on
  every surface downstream; there is nothing else to remember.
* **Consume a secret where you receive it.** Reveal it and act on it — persist it
  through the config API, hand it to the provider call that needs it — in the same
  live call that produced it. Do **not** pass a wrapper onward as a task or chain
  result: cross-process transit is unsupported and fails loudly (the wrapper will
  not serialize onto the wire), by design, so a secret cannot silently ride a
  background handoff.
* **Do not wrap shareable values.** Ids, endpoint URLs, links, and other
  non-secret fields stay plain, so callers and models can read and act on them.
  Wrap only the value that must not be recorded.

## Logging and redaction

A secret a library logs by itself — a token in a request URL, a credential in a
logged config — never passes through a `SecretValue`. A plugin masks it by
registering a redactor with the kit, never by installing a logging hook of its
own:

* `tai42_kit.logging.register_record_redactor(name, markers=..., redact=...)` adds
  a rule to the process record factory, which scrubs every record of the tai
  logger family (every record of the process under the `tai` CLI) at creation,
  before any handler sees it.
* `tai42_kit.logging.register_transport_redaction(name, markers=..., redact=...)`
  adds a rule to the one filter on the `httpx` and `httpcore` loggers, which render
  outbound request URLs.

`markers` are plain substrings; a record that carries none of them costs one
substring scan. A matching record is rendered once, passed through `redact`, and
its arguments cleared, so no formatter re-reads the raw values; exception and
stack text are scrubbed the same way. A redactor that raises fails the record
closed: its text becomes `[log redactor error: record suppressed]`. Registering
the same `name` again replaces the rule. For URLs in messages, the kit also
provides `redact_url_userinfo` (`https://***@host/...`) and `redact_urls_in_text`
(userinfo and every query-string value masked).

The Telegram channel keeps its bot token (which rides every Bot API path) out of
the `httpx` request lines this way:

```python theme={null}
import re

from tai42_kit.logging import register_transport_redaction

_BOT_TOKEN_RE = re.compile(r"/bot\d+:[^/\s\"']+")

register_transport_redaction(
    "telegram-bot-token",
    markers=("/bot",),
    redact=lambda text: _BOT_TOKEN_RE.sub("/bot<redacted>", text),
)
```

## Example

A generic tool that mints a one-time secret returns it wrapped, and writes it
nowhere itself:

```python theme={null}
from tai42_contract.app import tai42_app
from tai42_contract.secrets import SecretValue


@tai42_app.tools.tool
async def mint_signing_secret(label: str) -> dict:
    """Mint a signing secret and return its id and one-time value."""
    created = await provider_mint(label)
    return {
        "secret_id": created["id"],
        "secret": SecretValue(created["value"]),
        "label": label,
    }
```

Run it from the Studio or the run-tool API and the response carries the real
`secret` once. A second tool consumes it in the same synchronous call — revealing
it only to write it into the env under a name the server later reads it back by:

```python theme={null}
@tai42_app.tools.tool
async def store_signing_secret(label: str) -> dict:
    minted = await tai42_app.tools.run_tool("mint_signing_secret", {"label": label})
    tai42_app.config.config_manager.write_env(
        {"VENDOR_SIGNING_SECRET": minted["secret"].reveal()}
    )
    return {"secret_id": minted["secret_id"], "stored": True}
```

The [Stripe tools plugin](/plugins/tai42/tools-stripe) ships this pattern for a
real integration: creating a webhook endpoint returns the endpoint id plus its
one-time signing secret wrapped in the envelope, so the secret reaches the caller
that persists it but is written to no config, env, or file along the way.

See [config and secrets](/concepts/config-and-secrets) for the stored-secret
side, [presets](/concepts/presets) for wrapping a secret-producing tool, and
[interactions](/concepts/interactions) for collecting one from a person.


# States
Source: https://docs.tai42.ai/concepts/states

A declared JSON document, one per subject, that every door reads and writes through one platform store.

A **state** is a declared JSON document with one instance per **subject**. The
platform owns the store: a conversation turn, a hook fire, a scheduled job, a
builtin tool, and the HTTP API all read and write the same subject's document
through one seam, and every write lands in one audit trail. Domain behaviour —
which flow reads which state, how a record is shaped for a use case — lives in the
consumer that binds the state, never in the store.

The store is a first-class platform component. It ships with the platform but
serves nothing until its database is bound (see
[Enabling the store](#enabling-the-store)); until then every read and write refuses
loudly with a `501` rather than returning an empty document.

## The subject

A subject is four fields:

```json theme={null}
{
  "target_kind": "agent",
  "target_name": "A-42",
  "kind": "person",
  "key": "alice"
}
```

* `target_kind` and `target_name` are the **conversation-target scope** — the only
  tenancy the platform has. A subject never crosses this pair.
* `kind` names the subject family the state serves. Kind `person` is the one
  platform-validated family: its `key` is a person id resolved against the
  conversations identity store, and the resolved person's target must equal the
  subject's target. Every other kind is declared by the state and its key is
  opaque to the platform.
* `key` addresses one subject within its kind. It is trimmed and must be 1 to 512
  characters.

The store refuses a subject loudly (`422`) when its rule fires: an **undeclared
kind**, an **empty key**, an **unknown person**, or a **person whose target does
not match the subject's**. A subject `kind` is a lowercase identifier of at most
63 characters (`^[a-z][a-z0-9_-]{0,62}$`).

## Declarations and kinds

A state is declared before it is written. A declaration names the state, its base
JSON Schema, the subject kinds it serves, and the default kind a door's ambient
subject resolves to:

```json theme={null}
{
  "name": "status",
  "description": "Per-person status document.",
  "schema": { "type": "object", "properties": { "note": { "type": "string" } } },
  "subject_kinds": ["person"],
  "default_subject_kind": "person",
  "retention_days": 90
}
```

* `subject_kinds` is a non-empty, unique list; each entry matches the subject-kind
  charset above.
* `default_subject_kind` must be one of `subject_kinds`. It is the kind a door's
  **ambient** subject resolves to when no explicit kind is named (see
  [Doors](#doors)).
* `retention_days` is optional: a positive integer, or unset to keep records
  forever.
* A state `name` matches `^[a-z0-9][a-z0-9_-]*$` — no colon, because the write
  op-id namespace splits on `:`.

Two schema fields are **computed by the platform** and served on every read:
`effective_schema` (the base schema composed with every attached template's fragment)
and `regimes` (the absolute write-regime rules composed over the attachments). A client
that supplies a non-null value for either on a write is refused — neither can be
forged across the wire.

### Re-declaring

Once records exist, a re-declare accepts only **additive** schema changes: a
re-declare that would **remove or change** an existing field while records exist
is refused (`409`), and removing a subject kind still present in records is
refused the same way. `retention_days` is metadata, not schema, so changing it
alone is never gated.

## Templates and attachments

A **state template** is a reusable schema fragment with fillable parameters,
per-path writer regimes, attach-time declarations, a set of **template jq** programs,
an optional **reconcile** program, and a trace switch. It is a document the platform
owns:

```json theme={null}
{
  "kind": "state-template",
  "name": "utilities",
  "description": "A reusable fragment.",
  "parameters": {},
  "schema": { "type": "object", "properties": { "items": { "type": "array" } } },
  "regimes": [{ "path": ["items"], "regime": "composing" }],
  "template_jq": {},
  "reconcile": null,
  "trace": { "enabled": true }
}
```

A state template is data and the store is generic: nothing in a template is a use-case
feature — it is a mechanism any state can reuse. A `name` is a **slug** —
`^[a-z](?:[a-z0-9]|-(?=[a-z0-9])){0,62}$`, so no leading, trailing, or consecutive hyphens —
because a template name is a URL path segment (`/api/state-templates/{name}`). A document that
carries keys outside its own schema is refused, so an operator who pastes a whole consumer
document is told exactly where those belong.

Every section is typed:

| Section | Shape |
| - | - |
| `parameters` | `{name: {schema, default?}}` — `default` is absent when the parameter has none (an explicit `null` is a default) |
| `regimes` | `[{path, regime}]` — `path` is a list of non-empty keys or `"*"` (`[]` is the root); `regime` is `single`, `composing`, or `free` |
| `trace` | `{enabled}` — a boolean, `false` when the template declares no switch |

![The studio page of the state template display on its Template tab: the Fields schema, a Write policies table with the path density under the single regime, a Parameters table with default\_density, its enum schema of compact and comfortable and the default comfortable, and the line Trace writes: On.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/state-template-typed-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=3491b7b9f87277603e78b3b386922375)

A state template in the studio, each section shown typed.

A shipped default template (a seed) is validated exactly like an upload; a seed that does not
validate stops the boot, naming it.

### Rendered templates

The platform also serves a template **rendered**: every program body (inline or a stored `id`)
as jq text, a stored fragment as its schema, and the input programs in dependency order
(`input_order`). The states facet serves it three ways — `get_rendered_template(name)`,
`rendered_attachments(state)` (every attachment on a state with its rendered template), and
`render_template(document)` for a candidate not yet stored. Each carries an opaque `version`
that changes whenever anything the rendering read changes; compare it for equality only.

### Template jq

A template's `template_jq` is a map of named jq programs a door or a flow node runs against
a subject's record, each declaring a **`purpose`**:

* **`input`** — `{description, purpose: "input", params, jq}`. `jq` runs over the record
  subtree at the attach path (`.` is the attached data) with the effective `$parameters`, the
  `$declarations`, and its declared `params` delivered as the single object `$params`, and
  returns a value. Read-only.
* **`update`** — `{description, purpose: "update", params, reads, writes, jq}`. `jq` runs over
  the record's attached subtree (`.` is the current data at the attach path) with the caller's
  argument bound as [`$input`](/concepts/jq-variables#template-jq) and `$parameters`/`$declarations`
  bound, and returns an ordered,
  template-relative op batch (the keyed-op shape the store applies). `params` are the key
  names the `$input` object must carry — uniform with an `input` program's `params` — so apply
  refuses an `$input` missing a declared key or carrying an undeclared one (`422`); a named
  update that declares `params` needs an
  [adapter](/babelfish#binding-a-node-to-a-state) in a binding to fill them. `reads`/`writes`
  are template-relative paths declared for readability; at put each `reads`/`writes` path is
  validated only for **structure** — that it resolves against the fragment — while the
  **write regime** (that a `writes` path lies under a declared-writable regime) is enforced at
  apply by the store guard.

A program is named by reference, resolved by one rule wherever a reference is used — an
evaluate or apply call over HTTP, MCP or the CLI, a binding validated or saved on a door or a
babelfish node, and a binding's run:

* **`<template>.<name>`** names that template's program. The template must be attached on the
  state and declare the program, else `404`.
* An **unqualified `<name>`** resolves to the one template attached on the state that declares
  it. None declaring it is `404`; two or more is `422`, naming them and asking to qualify it as
  `<template>.<name>`.
* The program's **purpose** must be the caller's: an evaluation or an input injection needs an
  `input` program, an apply or an update an `update` program; a mismatch is `422`
  (`template_jq 'x' on template 't' has purpose 'update', needs 'input'`).

A door binding validated without attaching (a dry run) resolves as though each of its own
templates not yet attached were attached at `[<template>]`, so the reference it accepts is the
one its runs resolve. A babelfish node binding resolves through the same rule and also refuses a
reference to a program of a template the binding does not attach.
The states facet serves the rule as `resolve_template_jq(state, name, *, purpose, declared=())`,
returning a `ResolvedTemplateJq` (`template`, `program`, `purpose`, `params`, `path`); `declared`
names templates a caller is about to attach. `resolve_template_jq_batch(refs)` resolves a list of
`TemplateJqReference`s (`state`, `name`, `purpose`, `declared`) in one call: one statement reads
every named state's declaration version, and each reference resolves against its state's catalog at
that version. A write that lands on a state during the call can make any reference on that state —
the first one too — read the catalog's current rows and resolve against the newer version. Its answer holds one item per reference, in order:
the `ResolvedTemplateJq`, or the `StateNotFoundError` / `ValueValidationError` that
`resolve_template_jq` raises for that reference, with the same message, so one refused reference
never hides the others' verdicts.

Sibling `input` programs are ordered dependency-first, so one may call another by name. A
[binding](/babelfish#state-templates) on any door (or a babelfish node) injects an `input`
program's value into a run's input before the run and applies an `update` program's batch
after it; the record-level HTTP and CLI surfaces evaluate an `input` program and apply an
`update` program directly (see [Template jq](#template-jq-1)).

A binding applies its whole update set in one transaction — every engaged state's
updates land together, and if any update fails the run's writes roll back as a
unit. The atomicity is automatic; nothing configures it.

### Attaching

**Attaching** a template places its fragment at a path in a state's document. The template is
named in the URL segment (`PUT …/attachments/{template}`), never in the body; the body carries
only `path`/`parameters`/`declarations`/`options` (the last a per-operation, never-stored bag):

```json theme={null}
{ "path": ["extras"], "parameters": {}, "declarations": {}, "options": {} }
```

The effective schema is the base schema with every attached fragment composed in. Composing
two fragments at overlapping paths, attaching a second template at an already-occupied path,
or attaching where the base schema already carries the property is a conflict (`409`) naming
the colliding path.

A fragment's local `$ref`s keep the fragment's meaning once it is placed: a pointer
reference (`#` or `#/…`) is rebased to the attach path, so `#/$defs/t` in a fragment
attached at `["box"]` reads `#/properties/box/$defs/t` in the effective schema, while an
anchor reference (`#name`) is left as it is. What a fragment may carry:

* **With its parameters filled in**, the fragment must be a valid draft 2020-12 schema.
* **At a path**, a pointer reference whose target sits inside a `const` or `enum` value is
  refused: that value is data a record must equal, and rebasing the reference would change
  it.
* **At the root** (`path: []`), the fragment's root `type` must be `object`, and its root
  may carry only `properties`, `required` and `$defs`, which merge into the state's root
  (a key the root already holds is a conflict, as a property is). Annotation keywords
  there (`title`, `description`, `$comment`, `examples`, `default`, `deprecated`,
  `readOnly`, `writeOnly`, and a `$schema` naming draft 2020-12) are dropped; any other
  root keyword is refused. A pointer reference must name a target under
  `#/properties/<key>` or `#/$defs/<key>`; `#` or any other root pointer would name the
  state's root once merged, so it is refused. Attach such a fragment at a path instead.

The effective schema then meets the same rules as a declared schema. It is held to the same
JSON Schema rules as a [form's schema](/concepts/interactions#shapes-are-caught-inside-the-form),
and it is one draft 2020-12 document, so:

* a value a validator cannot use is refused: a `pattern` that does not compile,
  `patternProperties` keys that cannot be combined, a bound that is not a finite number;
* every `$ref` resolves to a valid schema: `#`, a `#/…` pointer, a `#anchor` or an absolute
  reference under the root `$id`, or into a JSON Schema meta-schema by its URI (no schema is
  ever fetched); a `#/…` pointer indexes an array only with `0` or a whole number without a
  leading zero;
* `$dynamicRef`, a `$schema` naming a dialect other than draft 2020-12, and a `$id` below the
  root are refused, and so is a root `$id` that is a meta-schema's URI;
* an anchor name is unique across every `$anchor` and `$dynamicAnchor` in the schema, and a
  `$dynamicAnchor` below the root that a meta-schema a reference leads to would jump back to
  is refused, as for a form;
* a cycle of references that never descends into the document is refused.

These rules are checked whenever an effective schema is composed, so a declaration, an
attach, a declarations write, a detach or a template replace whose result breaks one is
itself refused.

A template's parameter `schema` and its `declarations.schema` are held to the same rules:
each must be a valid draft 2020-12 schema whose `$ref`s resolve by the rules above. A template
breaking this is refused when it is saved, previewed or seeded.

A consumer may register an **attach validator** on the states facet with
`register_attach_validator`: given the state name, the template document, the attachment's
declaration values, and the state's effective schema, it raises loudly to refuse an attach or a
declarations write — it is consulted before every attach, every declarations write, and every
template replace (once per live attachment).

### Attach reconciliation

Replacing a live attachment's `declarations` can retire part of a template while the state
still holds OPEN records shaped by the old declarations. The platform runs a built-in
**reconciler** that reads the template's `reconcile` program, and a consumer may register its
own with `register_attach_reconciler(reconciler)` — a pre-write hook run inside every `attach`
and `update_attachment_declarations` write, after the validators and before the write. It
receives an `AttachReconcileContext`: the `state` name, the template document, the `operation`
(`attach` | `update_declarations`), the `previous_declarations` (`None` on a first attach) and
`new_declarations`, the attach `options`, and a record door bound to the state. The reconciler
either **raises** to refuse the attach (naming the records the new declarations would orphan)
or **writes resolutions** through the context's record door and returns, letting the attach
commit with those writes.

The `options` bag on the `PUT`/`PATCH` attach body (`AttachBody.options`, `--options` on the
CLI) is a free-form, **per-operation** directive bag the reconciler reads to decide how to
settle open records against the new declarations — for example, whether to close records the
new declarations no longer cover. It is passed to the reconcilers for THIS attach only,
**never stored or served back**; any key outside
`path`/`parameters`/`declarations`/`options` is refused.

### Detaching

Detaching a template is guarded so a live reference is never stranded. The detach door
consults every registered **detach referee** before it removes the attachment and refuses
(`409`, listing the human-readable references each referee returns) while any binding still
calls the template's [template jq](#template-jq). The platform's own binding holders — preset
versions, conversation-route configs, hooks, and schedules — are checked, and any consumer that
registers a referee is too: the flow engine registers one for its
[per-node bindings](/babelfish#binding-a-node-to-a-state), just as it does against a state
delete. Nothing is auto-detached — the author removes or rewrites the referencing bindings
first, then detaches. A consumer registers a referee with `register_detach_referee`, beside
`register_delete_referee` on the tools facet.

### Regimes

A regime is a per-path writer rule composed over a state's attachments. Each rule is a
`{path, regime}` where the path may use the `"*"` wildcard (one list index or key)
and the regime is one of:

* **`free`** — no restriction. An undeclared path is `free`.
* **`composing`** — the path is built up by many writers, so a whole-path
  `set`/`remove` over it is refused (`422`); it admits only a keyed op or an append
  `set`. The refusal names the path and template, for example: `composing path ['items'] of template 'utilities' admits only keyed ops or an append set`.
* **`single`** — a single-writer path. This is enforced as an authoring check when
  a consumer binds a state, not at the store: a hook, schedule, or builtin-tool
  write on a `single` path is recorded in the audit trail with its door and actor,
  never refused at write time.

When a template's trace switch is enabled, the effective schema admits a `_trace`
object on every write under the attachment, and the platform stamps it (see
[The audit trail](#the-audit-trail)).

## Doors

Every door that can write a subject's document deposits one ambient
`StateContext` — the entering door, the resolvable subject candidates, and the
accountable actor — so a downstream write resolves its subject and provenance
without a per-door argument. The context is one generic object, so a run parked at
an async `ask` and resumed later rejoins the same attribution.

| Door | What it supplies | Explicit subject |
| - | - | - |
| **Conversation turn** | door `conversation`; the route's target scope; candidates `{"thread": <thread id>}` always, plus `{"person": <person id>}` on a multichannel target; actor = the turn's attribution user id; the turn id and inbound id | a flow reads the `turn.subject` block; a tool takes a `subject` argument |
| **Park → continuation** | the original turn's `StateContext`, stored whole beside the continuation identity and re-deposited when the run resumes | — |
| **Hook fire** | door `hook`; the declared target and `{kind: key}`; actor = the hook's execution key | a hook's `tool_kwargs` may carry `subject` |
| **Schedule fire** | door `schedule`; the job's `subject` under its target; actor `null` (the fire is anonymous) | the job's `subject` |
| **Builtin tools** | resolved from the ambient context, or from an explicit `subject` argument | `subject` argument |
| **HTTP API** | door `api`/`operator`; actor = the request principal | the subject is in the path |

A tool run with no ambient context — a sync run-tool call, a background run, the
MCP edge — is the `api` door and a state tool it calls must carry an explicit
subject; called with none it raises `no subject in scope`.

### Subject references

A binding's `subject_expr` result and a builtin tool's `subject` argument are both a
**subject reference**, resolved by one platform rule — the states facet's
`resolve_subject(state, ref)`:

| Reference | Resolves to |
| - | - |
| `{target_kind, target_name, kind, key}` | that subject, validated |
| `{kind, key}` | the ambient context's target, with that kind and key |
| a key string | the ambient target, the state's `default_subject_kind`, that key |
| omitted | the ambient target and the context's candidate for the state's `default_subject_kind` |

A reference that cannot be resolved is refused (`422`, `SubjectRefusedError`) naming the rule
that fired: a mapping giving only one of `target_kind`/`target_name`, no ambient context where
the form needs one, a blank key, no ambient candidate for the default kind, a mapping that does
not validate (naming each failing field), or any other shape. An undeclared state is `404`: a
key string or an omitted subject reads the declaration's `default_subject_kind` and is refused
there, while an object form resolves without reading the declaration and the record read or write
it addresses refuses it. A builtin tool's `subject` argument takes the two object forms or is
omitted.

### A binding's subject and scope

A [binding](/babelfish#binding-a-node-to-a-state) — on any door definition (a preset,
hook, schedule, or channel route) and, in babelfish, per node — resolves its subject with
a jq `subject_expr` and gates itself with an optional jq `scope_expr`. Both mean the same
on every door and every node:

* **`subject_expr`** is **required** and non-empty, and yields a
  [subject reference](#subject-references): a full subject object
  `{target_kind, target_name, kind, key}`, a `{kind, key}` object, or a bare **key** string —
  for a bare key the `kind` is the state's declared subject kind; for a key or a `{kind, key}`
  object the target is the run's ambient target. A `null` result, like a missing or empty
  `subject_expr`, is refused (`422`), and so is a reference that does not resolve.
* **`scope_expr`** is an optional **boolean** predicate over the run's inputs, evaluated
  first: `false` skips the state for that run — no input injections and no updates; a
  non-boolean is refused loudly; an absent expression means engaged.

When a door dispatches a preset that carries its own binding, the **door's `scope_expr`
wins** when present, else the preset's. A preset's own binding fires only when that preset
is the **outermost** dispatch; called as a sub-tool of another dispatch, its binding is a
no-op.

A binding fires on every door it reaches through, the MCP edge included: an MCP `tools/call`
that omits `arguments` still receives the binding's input injections — absent arguments are
treated as an empty argument object, never a skipped injection.

### Saving a binding

A binding is checked when the definition carrying it is **written** — a hook registered, a
schedule created, a preset created, saved as a version, or rolled back, a per-target
conversation config set. Each of these has one write service that the HTTP door and the
[backup restore](/operate/backup-and-restore#restoring-stored-definitions) both run: it compiles
the binding's jq slots, resolves each state's named template jqs in one `resolve_template_jq_batch`
call, and **attaches** every named template (attach-on-use, idempotent) before the definition is
stored. A refusal stores nothing.

At a door, the refusal maps by its exact error type:

| Refusal | Status |
| - | - |
| The binding names an undeclared state, a template that does not exist, or an unknown template jq | `404` |
| A named template's attach path is already occupied | `409` |
| A jq slot that does not compile, or binding content the store refuses | `400` |
| The states store is unbound or fails | `500` — a store failure is never reported as a bad binding |

The preset [validate](/concepts/presets) dry run runs the same checks **without attaching**,
and reports a refused binding as an invalid verdict; a store failure there is a `500` too,
never an invalid verdict.

In a backup restore the `states` section replays right after `templates` and before every
section that restores a binding, so the states and templates a restored binding names exist
by the time its definition is written.

### The turn subject block

Every tool turn's payload carries a generic `turn` block so a flow's
`subject_expr` can read the subject the platform resolved:

```json theme={null}
{
  "id": "<turn id>",
  "inbound": { "id": "<inbound id>", "kind": "message", "source": "<source>" },
  "subject": {
    "target_kind": "agent",
    "target_name": "A-42",
    "person": "alice",
    "thread": "<thread id>"
  }
}
```

`person` is `null` off a non-multichannel target (a person is resolved only for
multichannel targets); `thread` is always present.

### Hook and schedule subjects

A hook may declare an optional subject: the target scope, a subject `kind`, and a
`key_expr` — a jq expression evaluated over the event payload at fire, which must
yield a non-empty string, else the fire fails loudly like any hook error. A
schedule carries its `subject` in the job's tool kwargs; a malformed subject is
refused when the job is created (`invalid schedule subject: …`), so a job that
could never resolve its subject is never persisted. Both surface a **Subject**
group on their Studio forms; see [Hooks](/concepts/hooks) and the scheduling
reference.

## The builtin tools

Four LLM-facing tools read and write the calling subject's document. Each resolves
its subject from the ambient context, or from an explicit `subject` argument
(`{target_kind, target_name, kind, key}`, or `{kind, key}` with the target taken
from the context), by the same rule as a binding (see
[Subject references](#subject-references)); with neither resolvable it refuses, naming the
state, kind, and door.

| Tool | Effect |
| - | - |
| `state_read(state, subject=None)` | read the subject's document (a miss returns null) |
| `state_replace(state, data, subject=None)` | replace the whole document |
| `state_merge(state, patch, subject=None)` | shallow top-level merge of a patch |
| `state_apply(state, ops, subject=None, op_id=None)` | apply a batch of path operations |

The tools supply only the consumer half of a write's provenance (their tool name,
run, and — for `state_apply` — the idempotency `op_id`); the door, actor, and turn
id are stamped by the platform, never derived by the tool.

## The audit trail

Every write is recorded. A state's `writes` trail is a keyset page
`{items, next_cursor}` — the same paging idiom as `subjects` and record search — with
each `items` row carrying the write's `seq` and timestamp `at`, the completed origin
that produced it, and the absolute `paths` it touched. `next_cursor` feeds the next
call (`?cursor=`) and is null on the last page. The origin carries what the consumer
supplied — `consumer`, `meta` (an opaque object the writing consumer supplies — its own identifiers, for instance — stored and shown as is), `run_id`, `op_id` — and,
stamped by the platform write chokepoint from the ambient context, `door`, `actor`,
`turn_id`, and `inbound_id`. Because door, actor, and turn are stamped by the platform,
the trail cannot be forged by a consumer.

Under a **traced attachment** the platform stamps a `_trace` object on every write:
`at` is always present; `run`, `turn`, and `inbound` are the run, turn, and inbound
ids, or null when the writer has none (a hook, a schedule, the API, or a builtin
`state_*` tool has none); and `meta` is an opaque object the writing consumer supplies
— its own identifiers, for instance — stored and shown as is. A flow's binding write
and a hook's keyed write get the same stamp.

## Unit of work

A consumer that stages several writes and lands them together opens a **unit of
work** over the states facet, bound to the scope it owns. Every write set staged
against the unit runs through the same applier the persisted write path runs — the
guards, the path ops, the composing-shape rule — and is projected, not stored. The
whole-document schema is checked **once per touched subject per staged batch**, on the
document the batch leaves: a batch is accepted or refused exactly as one multi-op apply
would be (an intermediate document between two of its writes is never checked on its
own). A validation, composing-shape, or schema error raises at stage time and leaves
nothing of the refused batch staged.

While the unit is open, a read of a subject the unit has staged is served from the
**projection** — the committed document overlaid with the scope's staged writes in
order, so a later step reads its own earlier writes — while every other scope still
sees only the committed document.

`commit` writes the unit's validated intent — every staged batch, plus any calls deferred
with `defer_call` — as one **pending save** in one small transaction. On the serving loop `commit` returns before
the records are applied, so the run's reply never waits on the record writes; the save is applied
after the reply (see [Pending saves](#pending-saves)): every staged subject lands in one
transaction, all-or-nothing, and the save is removed in that same transaction. A subject whose
committed record and declaration are unchanged since it was staged gets its already validated
projected document written as it stands; a subject whose record, declaration, or `op_id` ledger
moved in the meantime has its writes replayed onto the latest committed document instead, under
the declaration as it stands at apply: a subject kind it no longer declares is refused, and the
schema is checked once per staged batch. The guards and `op_id` idempotency are authoritative at
apply; a replay whose answer differs from the staged projection is logged and counted. `commit`
returns the staged answers, the pending save's id, and the number of deferred calls. A unit that
staged nothing and deferred nothing writes no save.
`discard` drops the staging. A unit left open when its scope ends is discarded at
teardown and the discard is logged.

A committed or discarded unit refuses any further stage, savepoint, commit, discard, or
deferred call with `StateUnitClosedError` (a `RuntimeError`).

`defer_call(tool, arguments, *, run_id=None)` queues a tool call to run after the save's
records apply. The arguments must be plain JSON and the tool must exist, or the call is refused
at once with `DeferredCallRefusedError`. The call runs later under the identity, run attribution,
state context, and trace the caller had when it deferred it, as an outermost tool dispatch (so
authorization, retry policy, run recording, and tracing all apply), with the idempotency key
`<save id>:<index>` in its extras under `tai42/idempotency_key`. A discarded unit, or a
savepoint rolled back, drops the calls it deferred.

A **savepoint** nests inside a unit: writes staged in the child scope are kept on a
clean exit and dropped on an exception, rolling back only the child's writes and
never the parent's. Savepoints nest to any depth, so a nested run rolls back its own
writes within the enclosing unit.

The unit of work is a programmatic facet API for in-process consumers; it has no HTTP
route.

### Caches and consistency

Each process keeps derived artifacts of the catalog — a declaration's effective schema and its
document validator, its composed regime paths, a template's validated form, and its rendered
programs. Every declaration and template row carries a `version` drawn from one database sequence
on each write to it (an attachment write and an attached template's replace included), so a
version never repeats for a name, even when the row is deleted and re-created. Each artifact is
served only for the version read inside the statement that serves it, so a change made through
any process is seen by every other on its next read. A rendered program also keys on the resource
manager that rendered it, so a stored-resource upload, a cache eviction, or a reload re-renders;
a rendered template's `version` also changes whenever a re-render (after the template cache's
TTL, or on every read while that cache is off) produces different text.

## Pending saves

A **pending save** is the durable intent a unit commit writes before the reply: the staged
writes of every subject the run touched, and the calls it deferred. It is applied after the
reply, and every reader of its subjects waits for it, so a participant's next message reads its
own previous turn.

**Who writes one.** A flow run's unit commit, a door binding's updates on a tool call, and a
parked run's deferred binding updates each write one pending save.

**Applying.** On the serving loop the save is applied in its own task right after the commit
returns. Off it — a backend whose jobs run on their own loop, such as Celery — the records are
applied inline and the deferred calls are left to the next sweep pass; a backend whose jobs run
on the process's serving loop, such as ARQ, runs them in the worker right after the job. A
**sweep** runs in every serve process and backend worker every `STATES_OUTBOX_SWEEP_SECONDS`,
and applies any save left behind (a crash, a lost task, a retry that is due).

**Per-subject order.** Saves that share a subject apply their records in the order they were
written. A save applies its records and removes itself in one transaction; when it carries
deferred calls it moves on to them after the records land, and its calls start only once every
older save on its subjects is gone, so deferred calls on a subject run in order too. The records part is applied exactly once. A deferred call runs at least once: a
call interrupted by a process exit is re-run only when its tool declares `tai42/crash_resume`,
and otherwise the save fails.

**Readers wait.** A read, write, fold, erase, template-jq call, or write-history read of a
subject first applies the subject's pending save (or waits for the one being applied), bounded by
`STATES_OUTBOX_DRAIN_TIMEOUT_SECONDS`. When nothing is pending this costs no extra round trip:
the check rides on the subject lookup the read already makes. A subject's write history includes
its pending save. A tool call, a hook or schedule fire, a parked run's continuation, and a turn
also apply their subjects' pending saves when they start, and wait for those saves' deferred
calls to finish, so a run never starts behind its subject's earlier save.

**Failures.** A transient failure (a lost connection, a timeout, an unavailable dependency) is
retried with an exponential backoff from `STATES_OUTBOX_RETRY_BASE_SECONDS`, capped at
`STATES_OUTBOX_RETRY_CAP_SECONDS`, up to `STATES_OUTBOX_MAX_ATTEMPTS` attempts. Any other
failure, or the last attempt, marks the save **failed**, and the failure is loud: an ERROR log,
an entry in the operator notifications inbox, the `states_outbox_save_failed` platform event (see
[Hooks](/concepts/hooks)), and the `tai42_state_outbox_*` metrics (see
[Observe](/operate/observe)).

### Held subjects

A failed save **holds** its subjects until an operator retries or discards it. A newer save that
shares a subject with it is held behind it. A read or write of a held subject raises
`StatePendingSaveFailedError` (`409`, naming the save) rather than serve a record that silently
lacks the save; a wait that runs out raises `StatePendingSaveTimeoutError` (`503`). The run-tool
door answers the same `409` / `503`, and a turn that meets a held subject fails through the
route's ordinary error reply. On the agents stream the `stream.error` frame names the held subject.

The scans over a whole state treat a held save in one of two ways:

| Scan | Held save |
| - | - |
| backup export and restore of the state, `fold`, `erase`, deleting the declaration | refused, naming the save |
| `list_subjects`, `search`, `stats`, retention prune, attach, updating an attachment's declarations | skipped: the scan serves the committed records, logs a WARNING, and names the held saves in its `held` field |
| re-declare (`PUT /api/states/{name}`) | counted: the held saves' records count as present, so a re-declare that would invalidate one, or remove a subject kind one writes, is refused (`409`, naming the saves); any other re-declare is accepted and names the held saves in `held` |

A widening re-declare followed by a retry therefore repairs a save that failed on the
declaration. A tool rename waits for a pending save under the tool, and is refused while a held
save, or a save still running its deferred calls, writes under it.

### Retry and discard

| Method & path | Purpose |
| - | - |
| `GET /api/state-pending-saves` | list outstanding saves, newest first (`?status=` `outstanding` or `failed`, `?limit=`, `?cursor=`), with the totals of outstanding and failed saves |
| `POST /api/state-pending-saves/{id}/retry` | retry a failed save: its attempts reset and its records apply at once; answers its status after the records phase |
| `DELETE /api/state-pending-saves/{id}` | discard a failed save: its writes and calls are never applied and its subjects are released |

Only a failed save can be retried or discarded (`409` otherwise). A listed save carries its
status (`pending`, `calls`, `running`, or `failed`), run, states, subjects, the calls it runs
(kind and target), attempts, last error, failed phase, and times — never its record data or
call arguments. A discard is logged at WARNING with the principal who made it and writes an
operator notification. The same three operations are MCP tools, and `tai states pending-saves
list|retry|discard` on the command line (`discard` requires `--yes`). The
[Studio's States screen](/studio/screens#states) shows them in its Pending saves card.

## Checking records

A record is validated against its state's **effective schema** — the base schema
composed with every attachment — on every write. Two read-only doors check that same
conformance without writing, so a schema can be checked before a document is stored and
after a declaration or attachment changes what the schema admits.

* **A candidate, before it is stored.** `POST /api/states/{name}/records/validate`
  takes a candidate document as its whole body and checks it against the state's
  effective schema exactly as a write would, but stores nothing. The answer is a
  `RecordValidation` — `{fits, reasons}`. A document that fits is `{fits: true,
  reasons: []}`; one that does not is a **`200`** with `fits: false` and every `reason`
  a `{path, message}` ordered by JSON path, so a caller sees all of a document's misfits
  at once rather than only the first. Only a non-object body or an effective schema with
  a broken `$ref` is a `422`, and an undeclared state a `404`.

* **The stored records, against the schema as it stands now.**
  `GET /api/states/{name}/records/check` pages the state's stored records and reports the
  ones that **no longer fit** the current effective schema — the records a
  [re-declare](#re-declaring) or an attachment change left behind. The answer is a
  `RecordCheckPage` — `{checked, items, next_cursor, held}`. `checked` counts the records
  the page read, and `items` are the **misfits only**, each a `RecordCheckItem`
  (`subject`, `updated_at`, and the same path-ordered `reasons`). A page that read
  records but found none wanting therefore carries an empty `items` beside a non-zero
  `checked`. It pages like the subjects listing and record search — a keyset `?cursor=`,
  an optional `?kind=`, and a `?limit=` — and `held` names the subjects a
  [failed pending save](#held-subjects) made the scan skip.

* **Without a store.** The skeleton's
  [`RecordValidator`](/reference/python-sdk/skeleton-states#recordvalidator) checks a
  document against a state's effective schema the same way the candidate door does, with
  no server: build it from the `effective_schema` a state's read serves, or compose one
  with `compose_effective_schema` from the base schema and the attachments, then call
  `validate`. The answer is the same `RecordValidation`, with the same path-ordered
  `reasons`. Compiling the schema is the costly step, so build the validator once and
  reuse it for every document.

  ```python theme={null}
  from tai42_skeleton.states import RecordValidator
  from tai42_skeleton.states.templates import compose_effective_schema, validate_template

  # The `effective_schema` from GET /api/states/alerts, or composed from its parts:
  template = validate_template(template_document)
  effective_schema = compose_effective_schema(base_schema, [(template, ["box"], {})])

  validator = RecordValidator(effective_schema)
  result = validator.validate({"n": 1, "box": {"tag": 5}})
  # With a fragment that declares `tag` a string: result.fits is False and
  # result.reasons[0].path is "$.box.tag".
  ```

  Building the validator checks the schema by the declaration rules
  ([above](#attaching)) and raises `SchemaValidationError` for a schema they refuse.
  `validate` raises `ValueValidationError` for a document that is not a JSON object, and
  for a `$ref` it cannot resolve while validating.

The two doors are also on the command line — `tai states validate <name>` (`--data` / `--file`)
and `tai states check <name>` (`--kind`) — and the Studio's
[States screen](/studio/screens#states) runs the stored-records check from a card on a
state's Records tab.

## The HTTP surface

All routes are authed. Templates are a top-level sibling collection and prune is its
own route, so no literal segment sits on the `/api/states/{name}` position — a
state literally named `templates` stays reachable at `GET /api/states/templates` while
`GET /api/state-templates` lists templates.

### States

| Method & path | Purpose |
| - | - |
| `GET /api/states` | list declarations |
| `GET /api/states/{name}` | declaration, effective schema, attachments, regimes |
| `PUT /api/states/{name}` | declare (`?replace=`) |
| `DELETE /api/states/{name}` | delete a declaration |
| `GET /api/states/{name}/stats` | record and subject counts, and the held saves |
| `GET /api/states/{name}/attachments` | list attachments |
| `GET /api/states/{name}/attachments/{template}` | read an attachment (404 if not attached) |
| `PUT /api/states/{name}/attachments/{template}` | attach a template |
| `PATCH /api/states/{name}/attachments/{template}` | update an attachment's declarations |
| `DELETE /api/states/{name}/attachments/{template}` | detach |
| `GET /api/states/{name}/subjects` | list subjects (`?kind=&limit=&cursor=`) |
| `POST /api/states/{name}/records/search` | search records by document content |
| `POST /api/states/{name}/records/validate` | check a candidate document against the effective schema, storing nothing |
| `GET /api/states/{name}/records/check` | page the stored records that no longer fit the current effective schema |
| `GET /api/states/{name}/consumers` | what binds this state |

### Records

The subject is four path segments:
`/api/states/{name}/records/{target_kind}/{target_name}/{kind}/{key}`.

| Method & path | Purpose |
| - | - |
| `GET …` | read the record |
| `PUT …` | replace the document |
| `PATCH …` | shallow-merge a patch |
| `POST …/deltas` | apply a batch of path operations |
| `DELETE …` | erase the record |
| `POST …/fold` | fold this subject into another |
| `GET …/writes` | the audit trail |

### Template jq

The record-level jq programs a state's attached templates declare share one path, the
method selecting the purpose:

| Method & path | Purpose |
| - | - |
| `GET …/template-jq/{program}` | evaluate an `input`-purpose program (query params supply its `params`) |
| `POST …/template-jq/{program}` | apply an `update`-purpose program (body `{input?, op_id?}`) |

`{program}` is a program name, or `{template}.{name}` when a name is shared across the
state's attachments. A GET on an `update` program, or a POST on an `input` program,
refuses loudly.

### Templates and retention

| Method & path | Purpose |
| - | - |
| `GET /api/state-templates` | list templates |
| `GET /api/state-templates/{name}` | read a template |
| `PUT /api/state-templates/{name}` | upload a template (`?replace=`) |
| `DELETE /api/state-templates/{name}` | delete a template |
| `POST /api/state-retention/prune` | prune expired records |

Errors map to status: `501` when the store's database is unbound (a stable code
`states-not-configured`), `404` not found, `409` exists / in use / conflict / a subject held by
a failed pending save, `422` validation (schema, subject, regime, path, value), and `503` when a
subject's pending save is still not applied after `STATES_OUTBOX_DRAIN_TIMEOUT_SECONDS`.

## The command line

Two command groups mirror the HTTP surface. `tai states` manages declarations,
attachments, subjects, records, and the audit trail — `list`, `get`, `put`, `delete`,
`stats`, `attachments`, `attach`, `get-attachment`, `update-attachment` (its `--options`
carrying the per-operation reconcile directives),
`detach`, `subjects`, `search`, `validate`, `check`, `read`, `replace`, `merge`, `apply`, `template-jq`
(`eval` an input program, `apply` an update program), `erase`,
`fold`, `writes`, `consumers`, `prune`, and `pending-saves` (`list`, `retry`,
`discard`). `tai state-templates` manages template
documents — `list`, `get`, `put`, `delete`. Record commands take
`--target-kind`, `--target-name`, `--kind`, and `--key`; `apply`, `replace`, and
`merge` read their JSON from `--data` or a `--file`. See the
[CLI reference](/reference/cli).

## Enabling the store

The store is the `states` DB registry component. Like the `skeleton` component it
**defaults to the `default` database** when its binding is unset, so an ordinary
deployment serves the store out of the box. A deployment that wants records in a
separate database points the binding elsewhere with `TAI_DB_BINDING_STATES`, then
applies the component's migration chain with `tai db migrate`. Until the bound
database is configured, every read and write returns `501 states-not-configured`.

Record retention is opt-in: nothing is deleted until a retention is configured,
either per state (`retention_days` on the declaration) or as a deployment default
(`STATES_DEFAULT_RETENTION_DAYS`). `tai states prune` runs the sweep.


# Storage and resources
Source: https://docs.tai42.ai/concepts/storage-and-resources

The ResourceManager and stored content.

Storage is where a server keeps content, and the ResourceManager is how tools and
templates read it. The manager loads content by storage id, url, or a raw file — as
text or as media — and renders Jinja templates fetched through the active storage
provider.

## The storage provider

Storage is a provider behind one ABC. The contract owns the `Storage` ABC and its
root-delete guard; the skeleton adds a registry that holds the one active provider.
A concrete provider — a local filesystem or object store — ships as a separate
[plugin](/concepts/config-and-secrets) and registers through `tai42_app` when the
[manifest](/concepts/manifest) names its `storage_module`.

## The ResourceManager

The ResourceManager layers on the active provider and resolves a resource from one
of three sources:

* **a storage id** — content stored under the provider,
* **a url** — content fetched from an address, or
* **a raw file** — content read directly.

It returns each resource as **text or media**. Media content is produced as typed
content parts, so a resource that is an image or other binary flows through the
same interface as text. Accessing the manager before a storage provider is
registered raises the moment a stored resource is first touched.

## Templates are stored resources

A template is one kind of stored resource. The ResourceManager renders Jinja
templates fetched through the provider, with a compiled-template cache in front of
the render step. Render mixins add `rendered_*` methods to the contract's field
models, so a stored template resolves in place wherever a field expects rendered
content.

A template write, a template delete, a directory delete — through `tai templates` or
the raw `tai storage` doors alike — a backup restore, or a manual
`tai templates clear-cache` evicts that compiled-template cache on **every** worker
over the [worker bus](/concepts/worker-bus), not only on the process that made the
change — so no worker keeps serving a template compiled from stale content, or keeps
treating a just-created template (or locale variant) as missing.

A plugin that caches something built from rendered templates follows the same eviction.
`tai42_app.storage.template_reads()` is a context manager that records, into the set it
yields, every template id a render inside the block reads — a by-id render's whole locale
fallback chain and every `{% include %}`, `{% extends %}` and `{% import %}` target. A
handler registered with `@tai42_app.storage.on_template_evicted` is called with a
`TemplateEviction` (one template id, a directory prefix, or every template; its `covers(id)`
answers whether an id is dropped) on every process that drops template content, the one
that made the write included. Keeping the recorded ids beside a cached entry and dropping
the entries the eviction covers refreshes exactly what read the changed content. The
babelfish flows engine caches its flows this way: a template write refreshes exactly the
cached flows that read it, on every worker.

### Locale variants

A template renders against the [subject's `locale`](/concepts/client-conversations#the-persons-locale)
when the render carries one — the template author never selects a language. A locale-scoped
variant lives at `"{id}@{subtags}"` (for example `greeting@he-IL`, `greeting@he`), and a render
for a locale walks a **fallback chain** from the most specific subtag form to the least, then to
the bare default id: `he-IL` resolves `greeting@he-IL` → `greeting@he` → `greeting`, returning
the first stored variant. When **none** of the chain is stored — no variant and no bare default —
the render refuses **loudly**, naming the template and locale, rather than silently rendering the
wrong language. A `None` locale (the locale-agnostic callers — hooks, authz, access control)
renders the bare id unchanged.

The locale also drives the **`list_format`** filter: a template writes `{{ names | list_format }}`
(with an optional CLDR list style, `standard` by default) and the separator and final connective
come from the resolved locale's CLDR list patterns. It reads the locale the render resolved, never a
template argument; a render that resolved no locale, or a locale with no CLDR data, raises loudly.

## Managing stored content

Two CLI groups reach stored content. `tai templates` is the higher-level,
template-aware surface (render, cache), while `tai storage` is the raw
provider-resource surface — thin wrappers over the authed `/api/storage*` routes:

```bash theme={null}
tai storage info                                  # provider identity, or the empty state
tai storage list                                  # the stored resource ids
tai storage upload notes/todo.txt --text 'buy milk'
tai storage stat notes/todo.txt                   # inferred content type
tai storage download notes/todo.txt               # raw bytes to stdout
tai storage delete notes/todo.txt
```

Storage is **dead by default** — the skeleton ships no provider. With none
registered, `tai storage info` reports the empty state (`present: false`, a `200`
so a UI renders it cleanly) while every CRUD door answers an honest `501` rather
than a fabricated default. A resource id must be a relative path with no `..`
segment; an absolute path or a `..` traversal is rejected with a `400` before it
reaches the filesystem-backed provider. Upload takes exactly one of `--text` (verbatim)
or `--base64` (decoded bytes), and an existing id is overwritten.

The presence answer (`GET /api/storage` / `tai storage info`) is a core,
always-mounted read: it is answerable in every deployment, including one that mounts
no storage management surface, so a consumer can always tell "no provider" apart from
"cannot ask".

The template-aware surface is the same content viewed as renderable resources:

```bash theme={null}
tai templates list
tai templates get <id>
tai templates upload prompts/greeting.md --file greeting.md
tai templates render --text '{"id": "<id>"}'
```

Stored content is one of the sections the [backup](/operate/backup-and-restore)
surface can export and restore.

> [!NOTE]
>
> A specific storage provider's configuration — its bucket, credentials, or paths —
> lives in that provider package's own repository, reachable from the
> [Plugins section](/plugins). The platform documents the storage
> contract, not any one provider.

See the [manage-stored-content guide](/guides/manage-stored-content) for the media
in-and-out workflow and the [Python SDK reference](/reference/python-sdk/index) for
the `Storage` ABC and the `ResourceManager`.


# Tool organization
Source: https://docs.tai42.ai/concepts/tool-organization

Folders, display names, tags, and visibility — an unversioned metadata overlay over any tool.

A running server can register hundreds of tools — your own functions, mounted MCP
servers, the standard toolbox, [presets](/concepts/presets), and Babelfish
[flows](/babelfish). **Tool organization** is the layer that makes that namespace
navigable: an editable overlay of folders, display names, tags, visibility, and
informational capability badges that sits *beside* every tool without touching
what the tool does.

## The overlay

The overlay is an **unversioned** organizational layer, keyed by tool name and
kept separate from any tool's behavior. It applies to **any** tool in the
namespace — a native plugin tool, a preset, a flow — never a preset-only concern.
It has two parts:

* **Folders** — real folder entities forming a tree. A folder has a name and an
  optional parent; nesting is endless through the parent chain.
* **A per-tool row** — for each tool that has one: its display name, the folder it
  is filed in, its user tags, and its visibility. Most tools never own a row —
  a tool with no row simply renders under its own name, unfiled, with only its
  native tags.

Because it is unversioned by design, editing the overlay never appends a tool
version or rebinds anything. It is metadata *about* the tool, not part of the
tool's behavior, so it rides no version history: a display-name change or a folder
move takes effect immediately and is not something you roll back through the
[versioning spine](/concepts/versioning-spine).

## Display names

A per-tool row may set a `display_name` that overrides the label a UI renders.
When set, surfaces show the display name; when absent, they fall back to the tool
name. The real tool name stays identifiable — most surfaces render it beside the
display name, and where a compact surface shows the display name bare the raw name
is one picker or edit surface away — so a display name is a friendlier label, never
a rename. The name a caller invokes is unchanged.

The display name follows a tool everywhere the Studio lists one to choose: the
preset create form, agent composition, schedule creation, extension apply, and the
Connectors page's MCP config each label a tool **Display Name (raw\_name)**, with the raw name
alone as the fallback. Agent composition's selected-tool chips are the compact
exception — they carry the bare display name, with the raw name one picker or
edit surface away. A plugin's own surfaces label the same way.

A display name is distinct from a tool's **description** (its LLM-facing docstring)
— the description is the tool's own behavioral text, while the display name is
purely a human label in the overlay.

## Folders

Folders are entity-backed, not a string on each tool. You create a folder (at the
root or under a parent), rename it, move it to a new parent, and delete it. The
store enforces the tree's integrity:

* **Sibling names are unique** within a parent (root folders share the empty
  parent), so no two folders in the same place collide.
* **A move that would form a cycle is refused** — a folder can never become its
  own ancestor.
* **A delete requires the folder empty** of both subfolders and tool rows — you
  cannot orphan its contents by removing it.

A UI renders folders as a current-directory explorer with a breadcrumb: the
current folder's subfolders first, then the tools filed directly in it, with
unfiled tools living at the root.

## Tags: two sources, one merged view

A tool can carry tags from **two independent sources**, and UIs show them merged:

* **Plugin-native tags** are code-owned and **read-only**. A plugin declares them
  on the tool itself (for example, `tags={"acme"}` on a tool registration),
  so they ship with the tool and cannot be edited from a UI.
* **User tags** are the overlay's editable set. You add or replace them on a
  tool's overlay row, and they persist independently of the plugin's own tags.

A tool's effective tag set is the union of the two. Grouping and filtering a tool
list works over that merged set, so a tool declared `acme` by its plugin and
tagged `reviewed` by you appears under both.

## Capability badges: informational, never enforced

Alongside tags, a tool can carry **capability badges** — short labels that flag
what a tool touches or does, meant purely to inform the human scanning a tool
list. Like tags, badges come from **two independent sources** and UIs show them
merged:

* **Plugin-declared badges** are code-owned. A plugin declares them on the tool
  itself (Acme's `acme_probe` declares `network`, for example), so they ship with
  the tool.
* **Operator-overlay badges** are the overlay's editable set, stored on a tool's
  overlay row and managed from the CLI or API.

A tool's displayed badges are the union of the two.

> [!WARNING]
>
> Badges are **declarative and informational only — never an enforcement boundary**.
> A badge such as `network` or `storage-write` describes a tool for a human reader;
> it grants and gates nothing. Never treat a badge as a permission — reach for
> [access control](/concepts/access-control) to actually constrain what a tool can
> do.

Badges are **free-form**: there is no fixed, enforced list. Any label from the
same charset the tag vocabulary uses is accepted — lowercase alphanumerics,
hyphens, and underscores (so no slashes; use the hyphen form like
`storage-read`). To keep badges legible across a deployment, a small **suggested**
generic vocabulary is worth standardizing on — as guidance, not a rule:

| Badge | Suggested meaning |
| - | - |
| `llm` | Calls a language model. |
| `network` | Makes outbound network calls. |
| `storage-read` | Reads from durable storage. |
| `storage-write` | Writes to durable storage. |
| `external-send` | Sends data to an external destination (email, webhook, …). |

Coin your own beyond these whenever a deployment needs a finer signal — the list
above is only a starting point, never a closed set.

## Visibility: hidden is not security

The overlay's visibility flag is **tri-state**:

* **Default** (no user opinion) — the plugin-declared visibility applies. A plugin
  may ship a tool hidden by default (Acme's `acme_probe` does), and with no
  overlay opinion that declaration stands.
* **Shown** — force the tool visible, overriding a plugin's hidden default.
* **Hidden** — force the tool hidden.

> [!WARNING]
>
> Hidden is **UI visibility only — never a security boundary**. A hidden tool is
> merely kept out of the lists; it stays fully registered and callable through the
> API. Never hide a tool expecting it to be unreachable — reach for
> [access control](/concepts/access-control) for that. A hidden tool has no reveal
> affordance in any UI; unhide it by setting its visibility to **Shown** from the
> CLI or API (`tai tool-meta set <tool> --visibility shown`).

## Lifecycle

An overlay row is keyed by tool name, so the platform keeps it in step with the
tools it describes:

* **A preset delete cascades** its overlay row away — deleting the preset removes
  the row keyed on its name.
* **A preset rename re-keys** the row to the new name, so the organization you
  gave a preset survives the rename that rebinds its tool.
* **A plugin uninstall keeps** the row. The tool it described is gone, so a UI
  hides the now-dangling entry; reinstalling the plugin brings the tool back under
  the same name and the row applies again.

## Managing the overlay

Edit the overlay from the CLI with `tai tool-meta` — folders and per-tool rows:

```bash theme={null}
tai tool-meta folder-create Research
tai tool-meta set web_search --display-name 'Web Search' --tag research --folder <folder-id>
tai tool-meta set web_search --badge network --badge external-send
tai tool-meta set acme_probe --visibility shown
tai tool-meta list
```

`set` is a merge-patch — only the flags you pass are sent, so omitting a field
leaves it unchanged. In the [Studio](/studio/screens) the Tools screen carries the
full per-tool edit dialog (display name, tags, folder, and the three-way
visibility control) plus folder navigation; hidden tools are excluded from the
screen outright, so unhiding is a CLI/API operation (set visibility **Shown**). The
Presets screen and the Babelfish Flows page edit the display name, tags, and folder
of the tools they list (hide management is centralized on the Tools screen).

## See also

* [`tai tool-meta` reference](/reference/cli/tool-meta) — the full folder and
  overlay command set.
* [The screens](/studio/screens) — the Tools screen's folders and edit dialog.
* [Presets](/concepts/presets) — a preset's own record carries no organization; it
  rides this overlay like any tool.
* [Babelfish](/babelfish) — flows organize through the same overlay from the Flows
  page.


# Tools and extensions
Source: https://docs.tai42.ai/concepts/tools-and-extensions

Atoms of work and the clip-on powers over them.

A tool is the atom of work: a plain Python function you decorate, a tool from a
mounted MCP server, or a management [operation](/concepts/live-operations) the
runtime projects. An extension is a clip-on power that wraps or transforms a tool
into a new variant. Everything else the platform does is built around these two.

## Tools

You register a function as a tool with one decorator on the shared `tai42_app`
handle. The function's signature becomes the tool's input schema, and its
docstring becomes the tool's description:

```python theme={null}
from tai42_contract.app import tai42_app


@tai42_app.tools.tool
def greet(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"
```

The tool registry keys each requested tool by its base name and maps it to its
extension combos. The dispatch adapters turn a vendor tool — an MCP tool or a
langchain tool — into a plain callable, so a tool from a
[mounted MCP server](/guides/bring-an-mcp-server) behaves like a local one. A tool
becomes live because the [manifest](/concepts/manifest) names its module.

A third source registers through the same binding: the management
[operations](/concepts/live-operations) — reload a tool, replace the manifest,
re-probe a failed MCP server. Each operation projects as a first-class tool (unless
[`api_tools`](/concepts/manifest#the-api_tools-block) curates it out), so an
extension wraps it, a [preset](/concepts/presets) bakes over it, and `tai tools
run` or an agent dispatches it exactly as with any other tool.

A tool can declare a **registration tier** (`read` / `write` / `fenced` / `secret`);
a `fenced` or `secret` tool is admin-only to author a preset over and to run,
enforced at the shared tool-run chokepoint on every door — see
[fenced tools](/guides/build-a-tool#fenced-tools).

## Retrying a tool call

A tool declares its own retry policy, and the host dispatch seam honours it. With
no declaration a dispatch is one attempt, exactly — retry is opt-in per tool,
never a platform-wide default.

```python theme={null}
from tai42_contract.tools import ToolRetryBackoff, ToolRetryPolicy


@tai42_app.tools.tool(
    retry=ToolRetryPolicy(
        max_attempts=3,
        idempotent=True,
        backoff=ToolRetryBackoff(initial_seconds=0.5, multiplier=2.0, cap_seconds=10.0),
    )
)
def fetch_quote(symbol: str) -> dict:
    """Read a quote from the upstream price feed."""
    ...
```

`max_attempts` is the **total** attempt budget with the first attempt included, so
`1` means no retry. `idempotent` is the author's explicit claim that re-firing the
body is safe: it is required, and a retrying policy without it is rejected — the
double-send guard.

`retryable` is the classification door, an explicit allowlist rather than a
blanket. `True` retries the default transient kinds, a tuple of `ErrorKind` retries
exactly those kinds, and `False` turns kind-based retry off. In every mode an error
that carries its own boolean `retryable` verdict wins in both directions — it
admits a failure that is off the list and vetoes one that is on it, because the
raiser knows its own failure better than any kind bucket. An error with neither a
verdict nor an allowlisted kind is never retried.

Backoff is exponential: attempt *n* waits
`min(cap_seconds, initial_seconds * multiplier ** (n - 1))` before the next one. A
server that answers with its own `retry_after` **widens** that wait when it asks
for longer — the cap bounds the platform's own growth, not the server's explicit
request.

> [!NOTE]
>
> A policy is declared on the **registered base tool name**. A
> [preset](/concepts/presets) runs the base tool's body with baked constants, so an
> undeclared preset inherits the first declared ancestor's policy — the idempotency
> claim travels with the body. An extension branch inherits nothing: its stack can
> compose or relocate execution the base never spoke for, so only an exact-name
> declaration arms it.

Every attempt is visible in [observability](/operate/observe) rather than collapsed
into one result, and the whole dispatch stays a single runs-index row whatever the
attempt count. See the
[Python SDK reference](/reference/python-sdk/contract-tools) for `ToolRetryPolicy`,
`ToolRetryBackoff`, and the retryable-kind constants.

## Extensions

An extension is a plain callable registered against an `ExtensionKind` and applied
to a tool. There are three kinds:

* **`WRAPPER`** — wraps the call around the tool without changing its input schema
  (for example, tracing or caching the call).
* **`TRANSFORMER`** — transforms the tool into a new shape, changing what inputs it
  presents.
* **`BACKEND`** — routes the tool's execution through a
  [backend](/concepts/backends).

The extension registry holds the registered extensions and enforces each kind's
cardinality rule. Applying an extension **branches** the base tool into a new
named variant rather than mutating it: attaching `monitor` to `mytool` binds a
`mytool_monitor` branch, leaving `mytool` itself untouched.

An extension whose branches can pause — a branch that dispatches a pausing tool and
passes its park through — registers with `pauses=True`:

```python theme={null}
from tai42_contract.app import tai42_app
from tai42_contract.extensions import ExtensionKind


@tai42_app.extensions.extension(kind=ExtensionKind.TRANSFORMER, name="relay", pauses=True)
def relay(func, orig_name, orig_desc):
    ...
```

A branch can pause when the tool it wraps declares `tai42/pauses` or when any extension in
its stack registered with `pauses=True`; any other branch is plain, and a park it returns
is refused like any [undeclared tool's](/guides/build-a-tool#tools-that-can-pause).

## Clipping an extension on

Extensions are attached in the manifest, separately from tool selection. A tool's
`extensions` map names the branch to build:

```yaml theme={null}
tools:
  - title: my_tools
    module: myapp.tools
    include: [greet]
    extensions:
      greet: [monitor]
```

A value may be one combo (`[ext]`) or a list of combos (`[[ext], [ext, other]]`),
and a stacked combo (`[[a, b]]`) layers both extensions onto one branch. The
extension's module must also be loaded — through `extensions_modules` — before you
can attach it.

## Built-in and contrib extensions

The skeleton ships two built-in extensions that depend on skeleton features:
`monitor` (a `WRAPPER` that traces a standalone tool call as one live span) and
`ask_external` (a `TRANSFORMER` that turns a callback-URL tool into an
[external interaction](/concepts/interactions)). Generic, self-contained
extensions — `chain`, `batch`, `cache`, and more — live in the `tai42-toolbox`
contrib package and load the same way. The
[standard toolbox guide](/guides/standard-toolbox) lists them.

> [!NOTE]
>
> An extension extends a single tool. A [plugin](/concepts/config-and-secrets) —
> a connector, storage backend, or config provider — extends the whole platform.
> The two are different things.

See the [Python SDK reference](/reference/python-sdk/index) for the `ExtensionKind`
enum and the tool registry surface, and the guides on
[building a tool](/guides/build-a-tool) and
[applying an extension](/guides/apply-an-extension).


# Transports
Source: https://docs.tai42.ai/concepts/transports

HTTP, SSE, STDIO, and the UDS path.

A transport is how a client reaches a server. You pick one when you start the
server, and clients connect over it. The runtime speaks HTTP by default and can
also serve over SSE, STDIO, or a fast same-machine Unix-domain-socket path.

## Choosing a transport

`tai serve` takes `--transport`. HTTP is the default; the MCP endpoint is then
served under `/mcp`.

```bash theme={null}
tai serve                        # MCP server over HTTP (default)
tai serve --transport sse        # MCP server over Server-Sent Events
tai serve --transport stdio      # MCP server over standard input/output
```

* **HTTP** — the default network transport, for MCP clients over the network.
* **SSE** — a streaming HTTP transport.
* **STDIO** — for a client that launches the server as a subprocess and talks over
  its standard streams.

## The UDS path

For same-machine communication, `--uds <path>` binds the server to a
Unix-domain socket instead of a host and port — a fast local path that avoids the
network stack. `tai42-kit` supplies the client-side UDS transports and a selector,
`get_mcp_transport`, that picks the right transport for a target: a UDS transport
for a socket, or a plain config for a networked server. A mounted external MCP
server can be reached over any of these — the manifest's `mcp` entry sets `url`,
`uds`, or `command` per server.

## Statefulness and workers

The HTTP transports are **stateful per process**: each MCP session is pinned to the
worker that created it. Under multiple workers a session opened on one worker
breaks when another worker handles its next request, so `tai serve` refuses
`--workers` greater than one on any stateful transport (`http`, `streamable-http`,
`sse`) with an error that names the fix.

The fix is `--stateless-http`, which turns on the underlying stateless HTTP mode and
lifts the refusal — for the HTTP transports only. It has no meaning for `sse` or
`stdio` (SSE has no stateless mode and STDIO has no HTTP sessions), so combining it
with either is itself refused.

More than one worker also needs the [worker bus](/concepts/worker-bus), or sibling
workers would serve stale config after a reload with no channel to converge on, and
shared [sub-MCP and hooks stores](/operate/deploy#scale-workers) (`SUB_MCP_REDIS_URL`
and `HOOKS_REDIS_URL`; `TAI_DEFAULT_REDIS_URL` stands in for them and the bus), or a sub-MCP app or
a hook registered through one worker would be unknown to its siblings. `tai serve`
hands its worker count to each worker, and each worker refuses to boot without them,
after it applies the stored env; `tai serve` then exits non-zero. So a multi-worker
HTTP server needs `--stateless-http`, `TAI_BUS_REDIS_URL`, and both stores.

| transport | `workers=1` | `workers>1` |
| - | - | - |
| stdio | ok | refused |
| sse | ok | refused |
| http / streamable-http | ok (stateful default) | refused unless `--stateless-http`, the bus (`TAI_BUS_REDIS_URL`) **and** the sub-MCP and hooks stores (`SUB_MCP_REDIS_URL`, `HOOKS_REDIS_URL`) |

Embedding the runtime in your own process applies the session-pinning rule the same
way: pass `create_app(manifest_path="manifest.yml", stateless_http=True)` to run
several workers. The bus and the stores, though, are a documented limitation when
you embed — the worker count reaches the workers rules only from `tai serve`, and
in-process code cannot count sibling processes, so a `create_app(...,
stateless_http=True)` factory run under an external `--workers` counts each process
as one worker and passes the workers rules even with no bus and per-process stores.
Set `TAI_BUS_REDIS_URL`, `SUB_MCP_REDIS_URL` and `HOOKS_REDIS_URL` yourself in any
multi-process embed. See
[Multi-worker and fleet sync](/operate/embed#multi-worker-and-fleet-sync).

> [!NOTE]
>
> Before binding a UDS path, `tai serve` cleans up a stale socket left by an unclean
> shutdown, but refuses to unlink a socket that answers a connect probe (a live
> server) or a path that is not a socket. This keeps one command from clobbering
> another server's socket.

See the [deploy guide](/operate/deploy) for choosing a transport in production and
the [CLI reference](/reference/cli/index) for the full `tai serve` options.


# Triggers and webhook verifiers
Source: https://docs.tai42.ai/concepts/triggers-and-webhooks

Firing tools from outside events.

A trigger fires a tool from something that happens outside the server — an inbound
webhook or a schedule. A webhook verifier is what authenticates an inbound webhook
over its raw bytes before its bound tool is allowed to run.

## Firing a tool from a webhook

The webhook path reuses two existing pillars. An external system delivers an event
to the public `/universal_webhook/{topic}` door; a [hook](/concepts/hooks) bound to
that topic then keeps the event and runs its tool in the background. A failure before
the hook acts that can pass is retried; a failure after it, or one no retry can change,
is held as a failed run (see [Kept and retried](/concepts/hooks#kept-and-retried)). So
"fire a tool from a webhook" is: map a topic to a tool with a hook, and point the
provider's webhook at that topic.

Because the topic rides the webhook URL as a single path segment, a hook's `name`
and `topic` must each be one URL-safe segment — `^[a-z0-9][a-z0-9_-]*$` (lowercase
letters, digits, underscores, and hyphens, opening on a letter or digit; no dots or
slashes). Registering a hook with a topic or name outside that charset is rejected
with a `400`.

> [!NOTE]
>
> A hook fires a **detached** tool run. An event that belongs to an existing
> **conversation** goes through the [event
> door](/reference/conversation-bridge#the-event-door) instead, so it enters that thread
> as a turn on the conversation's own FIFO rather than as a standalone run.

## Webhook verifiers

The public webhook doors — `/universal_webhook/{topic}` and the
[interactions](/concepts/interactions) callback — authenticate an inbound request
**over its raw bytes, before parsing**, through a named verifier resolved from the
webhook-verifier registry. A topic with no verifier binding is open by design; you
bind a verifier to lock it.

A binding has one shape everywhere — the contract's `TopicVerifierBinding`,
`{"verifier": <registered name>, "config": {...}}` — whether it locks a hook topic
(`PUT /api/hooks/topics/{topic}/verifier`), binds an `ask(verifier=...)` question, or is
[`ask_external`'s author config](/concepts/interactions#external-questions). Both doors run
the same verification and answer the same bodies.

Verification **fails closed**: a signature mismatch returns a constant `401`
(`{"error": "webhook verification failed"}`), and a missing verifier or secret, a verifier
bug, or a stored binding that is not a `TopicVerifierBinding` returns a `500`
(`{"error": "webhook verification error"}`) — either way nothing is recorded and no tool
runs. A body-signature verifier on the topic ingress refuses a `GET` with `405`. A verified delivery is then deduped against replay: on the
`/universal_webhook/{topic}` ingress a delivery whose per-delivery id was already
claimed within the replay window is a replay, answered with the idempotent
`already_seen` `200` and dispatching nothing. The delivery id is claimed in the same
store step that keeps the event's runs, so a delivery whose accept failed (the `500`)
holds no claim, and the sender's redelivery of it is processed.

## The built-in shared-secret verifier

The skeleton ships a `shared_secret` verifier that checks a named request header
against a secret read from an environment variable, with a constant-time compare.
A static secret carries no freshness, so its config also requires an `id_header`
naming a header the sender fills with a unique per-delivery id, which the ingress
dedupes on to refuse replays. Its config names the header, the env var holding the
secret, and that id header:

```json theme={null}
{ "header": "X-Webhook-Secret", "secret_env": "MY_WEBHOOK_SECRET", "id_header": "X-Delivery-Id" }
```

`config` also takes an optional `replay_window_seconds` (a positive int, default `86400`
— one day) setting how long a delivery id is remembered before the same id would be
accepted again.

The secret is referenced by env var **name**, never embedded — the binding carries
no credential. Provider-specific verifiers (for example a signature scheme for a
particular SaaS) ship as their own [plugin](/concepts/config-and-secrets) packages
and register the same way.

## Scheduled triggers

The other trigger is time. A [backend](/concepts/backends) schedule fires a tool on
a cadence or at a later time, naming the tool and its arguments — no external event
required.

A schedule may carry an optional **subject** in its tool arguments so a
[state](/concepts/states) write during the fire is keyed and attributed to the
job. Unlike a hook's key expression, a schedule's subject is a literal
`{target_kind, target_name, kind, key}` — the fire is anonymous, so nothing is
resolved from a payload. A malformed subject is refused when the schedule is
created, so a job that could never resolve its subject is never persisted. The fire
records the write under door `schedule` with no actor. The Studio's schedule dialog
surfaces the subject as an optional group.

A schedule is also a **parkable door**: with an execution key it carries the [door
contract](/concepts/asking-the-caller#the-door-contract) and drives the [parked
interactions](/concepts/asking-the-caller) on its subject each fire — see
[driving parked interactions](/guides/schedule-a-tool#driving-parked-interactions).

> [!NOTE]
>
> Every webhook door is throttled by the always-on [public-door flood
> limiter](/concepts/access-control#flood-control-on-public-doors), so an open door
> never ships without flood control.

See the [fire-a-tool-from-a-webhook guide](/guides/fire-a-tool-from-a-webhook) and the
[HTTP API reference](/reference/api/index) for the webhook routes.


# The versioning spine
Source: https://docs.tai42.ai/concepts/versioning-spine

One versioned-store primitive, many kinds.

One versioning primitive underpins the platform. Presets, access-control policies,
and authored agents do not each carry their own history machinery — they are typed
views over a single generic versioned-document store. Learn the spine once and it
explains all three.

```mermaid theme={null}
flowchart TD
    subgraph views["Typed views"]
        P["presets<br/>kind=preset"]
        A["AC policies<br/>kind=ac_policy"]
        G["authored agents"]
    end
    P --> S
    A --> S
    G --> S
    S["VersionedStore<br/>(kind, name) · opaque body · versions · rollback"]
```

## The store primitive

The versioned-document store is a `kind`-discriminated, body-opaque persistence
primitive: append-only version rows over an opaque JSONB body, an active-version
pointer, and rollback. Its identity is `(kind, name)` throughout, and every write
is one transaction. The store knows nothing about presets, policies, or agents — it
never inspects the body; the caller owns its shape.

Because identity is `(kind, name)`, a document can be **re-keyed**: `rename`
moves the active document `(kind, name)` to `(kind, new_name)` in one atomic
write. The whole version history, every per-version `tags` label, and the
active-version pointer move untouched — versions key on the document, not the
name, so nothing is copied and the body is never inspected. It raises loudly if
the source has no active row, or if the target name is already a live document. A
[preset](/concepts/presets) rename rides exactly this method.

It is a `runtime_checkable` Protocol, reached from the assembled app as
`app.versioning.store`, with its own record models (`DocumentRecord`,
`DocumentVersion`) and typed errors. Every method raises loudly on a missing,
duplicate, or invalid target rather than returning a silent default.

## Typed views ride the spine

A feature that needs history layers a typed view over the store under its own
`kind`:

* **[Presets](/concepts/presets)** — `kind="preset"`.
* **[Access-control policies](/concepts/access-control)** — `kind="ac_policy"`.
* **[Authored agents](/concepts/agents)** — a spec that versions the same way.

Each view owns the shape of its body and gets versioning, rollback, and
per-version tags from the spine for free. Because they share one primitive, a new
versioned kind is a new view — not a new subsystem.

## Where versions live

The spine's rows live in the framework's versioned-document tables, created by
the core migration chain the runner applies:

```bash theme={null}
tai db migrate
```

> [!NOTE]
>
> `tags` on a version is the generic per-version grouping label the store provides.
> It is distinct from any categorization a particular kind's body carries — a
> preset's own fields, for example.

See [presets](/concepts/presets) and [access control](/concepts/access-control)
for the views in use, and the [Python SDK reference](/reference/python-sdk/index)
for the `VersionedStore` Protocol and its record models.


# The worker bus
Source: https://docs.tai42.ai/concepts/worker-bus

How a config change reaches every worker.

The worker bus is how a live change reaches every process in a deployment. When
one worker persists a config change — a reloaded tool, a replaced manifest, a
soft restart, a [settings-profile](/concepts/config-and-secrets#settings-profiles)
apply, a compiled-template-cache eviction — the bus carries that change to every
other worker sharing the manifest and collects a per-worker outcome, so the whole
fleet converges instead of one process drifting ahead of its siblings.

## It is internal infrastructure, not a plugin

The bus is app-owned internal infrastructure, in the same class as the reload
gate. It is **not a [plugin](/concepts/config-and-secrets#the-plugin-model)** and
sits deliberately outside the plugin system: nothing about it is registrable,
swappable, or user-selectable, no manifest field chooses an implementation, and
there is exactly one bus. You do not author a bus or name one in a manifest — you
configure the single built-in with environment variables, and that is the whole
surface.

This is a deliberate line. A [backend](/concepts/backends) is a plugin — you pick
celery, rq, or arq. The bus is not: fan-out is the app's own concern, so a
backend-runtime process receives fleet changes through the bus exactly like a
serving HTTP worker, and carries no fan-out surface of its own.

## Enable it

The bus runs on a plain Redis, configured entirely through `TAI_BUS_*`
environment variables. Set `TAI_BUS_REDIS_URL` to turn it on:

```bash theme={null}
export TAI_BUS_REDIS_URL="redis://localhost:6379/0"
```

With `TAI_BUS_REDIS_URL` unset the bus is **off**, and the process runs on a no-op
local variant: a mutation applies in that one process and reaches no sibling. That
is the correct, supported shape for exactly one deployment shape — a single
worker, in `file` config mode, with no backend — and the wrong shape for every
other (see [Boot rules](#boot-rules) below).

Any plain, module-less Redis runs the bus — `redis:7`, `redis:8`, or `valkey`. No
Redis modules are required.

## Boot rules

Three deployment shapes cannot converge without the bus, so `tai serve` and
`tai backend` **refuse to start** without `TAI_BUS_REDIS_URL` when any holds:

* **More than one server worker.** Sibling workers would serve stale config after
  a reload with no channel to converge on. Under `tai serve --workers N` (`N > 1`),
  each worker refuses to boot busless.
* **A registered backend.** A manifest that names a `backend_module` runs a
  separate backend-runtime process that must converge with the server processes
  on every reload. This is re-checked on every reload, so a manifest or env change
  that *adds* a backend — or *removes* the bus while a backend remains — is
  refused too.
* **`TAI_CONFIG_MODE=kubernetes`.** The `kubernetes` config mode exists for multi-pod shared
  config, and a pod cannot see its own replica count, so `kubernetes` mode always requires
  the bus.

The refusal names `TAI_BUS_REDIS_URL`. A busless `kubernetes` boot is rejected on the
missing bus, not on a later kubeconfig error, because the `kubernetes` check reads only
boot-fixed env and runs before the config manager is built.

The workers check runs in each worker at its boot, after the stored env (the config-dir
`.env` or the config provider's store) is applied: a bus URL kept only in the stored env
counts, and a stored empty value over a value set in the container turns the bus off and
is refused. It counts the workers `tai serve` hands each worker in `TAI_SERVE_WORKERS`; a
process without that count counts as one worker. A worker that refuses fails its startup,
and `tai serve` exits non-zero. Every reload re-checks it, and a config write (an env
change, a manifest change, a profile replace) that would leave a multi-worker server
busless is refused. More than one worker also needs shared sub-MCP and hooks stores,
checked the same way — see [Scale workers](/operate/deploy#scale-workers).

A registered backend also requires a shared [hooks registry](/concepts/hooks#managing-hooks-live)
(`HOOKS_REDIS_URL`, or `TAI_DEFAULT_REDIS_URL`), at any worker count. The backend-runtime
process matches the events it raises against its own hooks registry, and an in-memory one
holds none of the hooks registered through the server, so those events would run no hook.
The rule is checked at the same points as the bus rule for a backend: `tai serve` and
`tai backend` refuse to start, every reload re-checks it, and a manifest or env change that
adds a backend over an in-memory hooks registry — or removes the hooks store while a backend
remains — is refused, naming `HOOKS_REDIS_URL`.

## Namespacing

`TAI_BUS_NAMESPACE` (default `tai`) prefixes the control channel, every reply
channel, and every presence key. Redis pub/sub is server-global — it is **not**
scoped by the numeric database index — so two deployments sharing one Redis would
cross-deliver each other's fleet ops unless they diverge by namespace.

> [!WARNING]
>
> When several independent stacks share one Redis, give each a unique
> `TAI_BUS_NAMESPACE`. Two stacks left on the default namespace deliver each other's
> reloads and manifest replaces to the wrong fleet.

## Worker identity

Every process on the bus holds a stable **slot name** — `{kind}-{n}`, where
`kind` is `serve` or `backend` and `n` is the lowest free ordinal, so the
processes of a fleet are `serve-1`, `serve-2`, `backend-1`, and so on. A worker
claims its slot atomically at boot and holds it for the life of the process. The
name is what you target a reload at and what every fleet surface labels a row
with — stable, not a fresh string each start. The busless local variant names
itself `serve-1` and is its own fleet of one.

Each slot also carries a **generation** — a life counter that increments every
time a process claims that name. A worker that restarts takes the same slot back
at the next generation, so `serve-1` at generation `4` is a later life of the
same slot than `serve-1` at generation `3`. The pair `{name, generation}`
identifies one life: a reply from a superseded life — a process that lost its
slot but has not yet noticed — is discarded on the generation, never mistaken for
the current one.

### The presence value

A worker advertises itself in a presence key whose value is the single source
every fleet surface reads:

| Field | What it carries |
| - | - |
| `kind` | `serve` or `backend`. |
| `pid` | The OS process id. |
| `generation` | The life counter for this slot. |
| `joined_at` | When this life claimed the slot — the fleet's join time. |
| `beat_at` | The last heartbeat — the "seen-since" a surface renders. |
| `state` | `ready`, `resyncing`, or `recycling` (below). |
| `last_op` | The last op this worker applied and its outcome — absent until it has applied one. |

The `state` is written live by the worker itself:

* **ready** — booted, resynced, and serving.
* **resyncing** — running its boot or reconnect resync; it converges to `ready`
  when the resync finishes.
* **recycling** — beginning a graceful self-exit (a recycle); it is on its way
  out, not coming back under this life.

### A blip does not drop a worker

The presence key carries a TTL (`TAI_BUS_HEARTBEAT_TTL`) that the heartbeat
refreshes at a third of its length. A deliberate shutdown deletes the key; a
transport blip does **not** — the worker leaves the key to its TTL and, on
reconnect, re-verifies it still holds the slot and beats again under the same
name and generation. A short connection wobble therefore leaves presence intact:
the worker stays the same life rather than vanishing and returning as a stranger.
Only a blip that outlasts the TTL — or a lost claim — ends the life; the next
claim of that slot then comes back at a higher generation.

### Reading a restart in progress

The `resyncing` and `recycling` states make a restart legible while it happens —
but a written state is only as trustworthy as the heartbeat behind it. Each
presence row is judged against the same freshness gate the bus uses to decide who
a broadcast can expect an answer from, and a row whose claim has decayed past that
gate is **stale**. So a worker in flux reads a few ways:

* A **fresh `resyncing` or `recycling` row** is genuinely restarting — the state
  is live and the heartbeat current.
* A **dead worker's row vanishes** when its TTL lapses; it is simply gone.
* A **`ready` row that has gone quiet** past the freshness gate is ambiguous — it
  is either reconnecting or already dead, and which is unknown until it beats
  again or its row expires. It is reported as `stale`, never labelled
  "reconnecting" on a guess.
* A **`resyncing` or `recycling` row that has decayed** past the same gate also
  reads as `stale`, not as its written state: a worker that died mid-resync or
  mid-recycle must not carry a promise it will converge.

## What the fleet report tells you

A mutation waits for the fleet and returns a **per-worker report** — one row per
worker, keyed on its name, with the op's outcome. Beyond a plain applied/failed,
the report names, honestly, every worker the change did not cleanly reach:

* **missing** — the worker is alive but never acknowledged the op inside the short
  ack window.
* **departed** — the worker's presence key expired; it went away (a rolling
  restart or a `SIGKILL` mid-reload).
* **timed\_out** — the worker acknowledged the op but did not finish applying it
  inside the apply window, which covers its full drain budget: its reload is stuck
  past it. Read that worker's log (the retire names the step that overran) and
  verify with the fleet census or a fleet reload.
* **resyncing** — the worker is mid-resync (a boot or a reconnect) and was not in
  a ready state to take the op; it converges on its own resync.
* **recycling** — the worker is departing under a recycle; it converges by ending
  its old life and leaving fresh capacity behind, not by applying this op.
* **stale** — the worker's row is past the freshness gate, so its state can no
  longer be trusted: reconnecting or dead, unknown until it returns or its row
  expires. A `stale` row carries no promise it will converge.

A worker that was not in a ready, freshly-beating state is reported as its actual
condition rather than silently skipped, so a broadcast stays honest about who it
could not expect an answer from. None of these outcomes is hidden: a worker the
broadcast could not converge is reported, logged, and surfaced in the UI — a
failed propagation is never a fake success.

A recycle-class env change — a [settings-profile](/concepts/config-and-secrets#settings-profiles)
apply or an env write (`tai config env set`, the Studio editor, a backup restore, a
plugin install) — drives one more thing over the bus: after the reload fans out, the
writer censuses the fleet on the bus and orchestrates a process recycle across the
serve/backend workers it names. Confirmation is by reality, not by tracking a name
to its successor — a recycle is accepted when two facts hold: the targeted **old
lives are gone** (their slots absent, expired, or already advanced to a higher
generation), and **fresh ready capacity** of each kind has booted under the new
config, counted per kind to cover the recycled workers. The report never claims a
particular new life is a particular old one's replacement; it confirms the old
lives ended and the fleet came back to strength. A target the bus could not confirm
(it was still applying the reload, so the recycle op got no acknowledgement) is
awaited on the census within the step budget; it may still recycle once its reload
returns, and its generation then bumps on `tai fleet workers`. The roll stops at the
first target that does not converge — reported `timed-out` or `failed` with a
`detail` — or when the bus cannot be read, and attempts neither the later targets nor
the writer's own recycle; `recycle_stopped` in the response names where and why. Because that census rides the bus
itself, the bus URL is one key a recycle can never carry — replacements would
register on a new bus the running census cannot see — so a profile changing
`TAI_BUS_REDIS_URL` is refused on every shape.

## Template-cache eviction over the bus

A change to stored template content evicts the compiled-template cache fleet-wide,
not just on the worker that made the change. A template write, a template delete,
a directory delete, and the manual `tai templates clear-cache` each broadcast a
cache eviction over the bus, and every worker drops the affected compiled
templates so none serves a stale compilation. The op response carries the same
per-worker `fanout` report the mutation pipeline returns — one row per worker — and
a worker that does not confirm the eviction is logged loudly rather than passed
over. A **directory delete** evicts by **prefix**: every compiled template under
the deleted path is dropped, and the eviction is idempotent — it converges even on
a partial failure, so a re-driven delete or a worker that missed the first pass
lands on the same end state.

On a persist-across-jobs backend — a **celery prefork** pool, whose forked
children hold their own in-memory caches for the life of the child — a
template-eviction or any registry-mutating fleet op turns the pool over **once**
after it applies, so a forked child can never take new work with a stale
compilation or a stale registry from before the change; a child finishing a job it
already holds exits after it and takes no further job.

## Documented limitations

The boot rules catch the shapes they can *detect from inside one process*. Some
multi-process shapes look identical to a legitimate single busless process, so the
rules cannot flag them for you. In every one of these, set `TAI_BUS_REDIS_URL`
yourself:

* **Only `tai serve` gives the worker count.** An external process manager
  (gunicorn, a supervisor, a container orchestrator) that drives the ASGI factory
  with its *own* `--workers` gives none, and the factory cannot count sibling
  processes, so each process counts as one worker and the workers rule never
  refuses. Set the bus, and the sub-MCP and hooks stores, in any multi-process
  deployment you run outside `tai serve`.
* **Single-worker fleets look busless.** A supervisor running many `tai serve
  -w 1` processes on one host, or several machines sharing one manifest over a
  network filesystem, pass every boot rule — each process legitimately sees
  `workers=1`, `file` mode, and no backend — yet run busless-stale. Set the bus in
  **any** multi-process file-mode deployment.
* **Mixed transports are undetectable.** A `stdio` or `sse` process sharing a
  manifest with an `http` fleet is another shape the rules cannot see.
* **A shared Redis needs a unique namespace.** Distinct stacks on one Redis that
  do not set unique `TAI_BUS_NAMESPACE` values cross-deliver fleet ops.

The rule of thumb: if two or more processes share a manifest, they need the bus,
whether or not a rule fires.

## Operational knobs

The timing knobs have safe defaults; change them only for a deployment whose
reloads legitimately run long. The apply window is never below three drain budgets
(`TAI_TOOL_RUNS_SHUTDOWN_DRAIN_SECONDS`): a reload's retire drains in-flight
requests, background runs and retired client pools in sequence, each within the
drain budget, and a worker draining real work must answer inside the window. A
bus-enabled process refuses to boot or reload, and a config change is refused, when
the window is below that floor; raise the window with the drain budget, adding the
reload's own time.

| Variable | Default | What it does |
| - | - | - |
| `TAI_BUS_REDIS_URL` | unset | Redis URL that enables the bus. Unset = bus off (single-worker, `file` mode, no backend only). |
| `TAI_BUS_NAMESPACE` | `tai` | Prefixes the control channel, reply channels, and presence keys. Unique per stack on a shared Redis. |
| `TAI_BUS_ACK_TIMEOUT` | `2.0` | Seconds the collector waits for the fast liveness acknowledgements before it budgets the rest of its wait toward the apply deadline. |
| `TAI_BUS_APPLY_TIMEOUT` | `90.0` | Seconds a mutation waits for every worker to finish applying — the report cut. Never below three drain budgets (refused at boot, on every reload and on every config change). The default covers three default drains, the fork quiesce, the MCP re-probes, the rebuild and the post-apply hooks; each post-apply handler receives the seconds left of it, measured from the worker's receipt of the op. |
| `TAI_BUS_HEARTBEAT_TTL` | `15.0` | Presence-key TTL. A worker refreshes it at a third of this; a transport blip leaves the key to this TTL and the worker re-verifies its slot on reconnect (presence survives a brief wobble), while a frozen or killed worker's row goes stale and then leaves the census within one TTL rather than blocking every op. |

## See also

* [Live operations](/concepts/live-operations) — the mutation surface the bus fans
  out.
* [Manage a fleet](/operate/manage-a-fleet) — inspecting the fleet and driving
  fleet-wide operations.
* [Backends](/concepts/backends) — the task-execution plugin, which the bus is
  deliberately not.
* [Config and secrets](/concepts/config-and-secrets#settings-reference) — the full
  environment-variable reference.
* [Deploy](/operate/deploy) — the multi-worker and `kubernetes` deployment shapes the boot
  rules gate.


# Installation
Source: https://docs.tai42.ai/getting-started/installation

Install the tai runtime and its packages.

Install the runtime from PyPI. `tai42-skeleton` pulls in the `tai42-contract`,
`tai42-kit`, and `tai42-cli` packages it builds on — `tai42-cli` provides the
`tai` command — so one install puts the whole runtime and the `tai` command on
your path.

## Requirements

* **Python 3.13 or newer.**
* **[`uv`](https://docs.astral.sh/uv/)** for the `uv add`, `uv venv`, and
  `uv pip install` commands below. The `pip` install needs no uv; the
  from-source flow does.
* **Redis 7.0+ and Postgres** only for the features that need them — for
  example access control (on by default), connectors, interactions, and the
  default `redis` checkpoint store, which needs a Redis with the RedisJSON and
  RediSearch modules. Local tools and mounted MCP servers need no services at
  all. [Infrastructure by feature](/operate/infrastructure) lists what each
  feature needs.

## Install

```bash theme={null}
pip install tai42-skeleton
```

Run that inside an activated virtual environment — a stock system Python refuses
a bare `pip install` with `error: externally-managed-environment`.

Or, in a `uv` project:

```bash theme={null}
uv add tai42-skeleton
```

## Add the standard toolbox

The `toolbox` extra pulls in the `tai42-toolbox` contrib package — its generic
tools and its composition extensions (`chain`, `batch`) load straight from a
manifest:

```bash theme={null}
pip install "tai42-skeleton[toolbox]"
```

See the [standard toolbox guide](/guides/standard-toolbox) for what ships in it.

## Add an identity provider

Access control is **on by default**, and the runtime refuses to boot when no
identity provider is registered — the skeleton ships none of its own. Install the
Redis-backed API-key provider and name it in the manifest — that is the pairing
every install starts from:

```bash theme={null}
pip install tai42-identity-redis
```

```yaml manifest.yml theme={null}
lifecycle_modules:
  - tai42_identity_redis.redis_api_key_provider
```

The provider stores key hashes in Redis, so an access-controlled server needs a
reachable Redis instance. [Access control](/concepts/access-control) explains the
policy model, and the [access-control guide](/guides/access-control) mints the
first key. For local work against tools that need no auth, turn the gate off with
`ACCESS_CONTROL_ENABLE=false` instead.

## Install from source

To run the skeleton itself — to read the code, run the shipped examples, or
build on an unreleased change — clone the `tai42` monorepo and install the
skeleton (at `core/skeleton`) into a fresh environment with `--no-sources`:

```bash theme={null}
git clone https://github.com/tai42ai/tai42
cd tai42/core/skeleton
uv venv --python 3.13
uv pip install --no-sources --editable .
```

`--no-sources` is what makes this single-package install stand on its own.
`tai42-skeleton`'s `[tool.uv.sources]` points its sibling `tai42-*` dependencies
at their monorepo workspace members for development; the flag ignores those
overrides and resolves them from PyPI instead. Install `".[toolbox]"` instead of
`.` for the standard toolbox, or `".[dev]"` for the test and lint tooling.

Run the checkout's commands with `uv run --no-sync`, which uses the environment
exactly as installed. A bare `uv run` re-syncs the project first, which puts the
`[tool.uv.sources]` overrides back and fails in a clone that has no sibling
checkouts beside it.

## CLI-only install

To operate a running server from another machine, install just the command-line
client — it pulls in none of the server runtime:

```bash theme={null}
pip install tai42-cli
```

Or, in a `uv` project:

```bash theme={null}
uv add tai42-cli
```

This puts the `tai` command on your path with the remote command groups — thin
clients over a server's `/api/*` routes. The full local tree (`tai serve`,
`tai db`, …) appears only when `tai42-skeleton` is installed alongside.

## The `tai` command

Installing the package puts the entrypoint on your path under two names, `tai`
and `tai42`. Both run the same command tree — `tai` is the documented one, and
`tai42` is an alias for environments where an unrelated `tai` already sits on
your PATH. Three subcommands run the long-lived processes:

* `tai serve` — run the MCP server.
* `tai backend` — run the agent / worker backend process.
* `tai metrics` — serve the Prometheus metrics endpoint.

Run `tai --help` for the full command tree, or browse the
[CLI reference](/reference/cli/index).

Next, boot a server and call a tool in the [quickstart](/getting-started/quickstart).


# Mental model
Source: https://docs.tai42.ai/getting-started/mental-model

How the runtime fits together in one page.

You bring a capability — a plain Python function, an agent, or an external MCP
server — and the runtime supplies the operational layer around it. MCP connects
tools to AI models but does not run them; tai is the server that does.

## The one diagram

Everything a server does hangs off two things: the packages it is built from,
and the manifest it loads.

```mermaid theme={null}
flowchart TD
    subgraph packages["The packages"]
        C["tai42-contract<br/>interfaces"] --> K["tai42-kit<br/>helpers"] --> S["tai42-skeleton<br/>the server"]
        C --> L["tai42-cli<br/>the tai command"] --> S
    end
    M["manifest.yml"] -->|loaded at startup| S
    S --> R["a running server"]
    R --> T["tools"]
    R --> A["agents"]
    R --> X["mounted MCP servers"]
    P["plugins<br/>connectors · storage · config · backends · monitoring · channels"] -->|register through tai42_app| R
```

## The layers

Four packages build on `tai42-contract`, each depending only on packages nearer
that leaf: `tai42-contract` declares the interfaces, `tai42-kit` supplies generic
helpers, `tai42-cli` provides the `tai` command, and `tai42-skeleton` is the
runnable server that implements the contract and extends the CLI. Read
[the layering](/concepts/layering) for the full picture.

Providers you do not write yourself — OAuth connectors, storage backends, config
providers, worker backends, monitoring, channels — ship as separate **plugins**. A plugin
registers through the shared `tai42_app` handle when the manifest loads it; no
plugin imports the skeleton.

## The manifest decides everything

A server loads exactly one [manifest](/concepts/manifest) at startup. It names
the tools, agents, extensions, external MCP servers, and plugin modules that make
up that system. Nothing loads automatically — a capability is present because the
manifest names it, and absent otherwise. An empty manifest boots a bare server.

## Tools are the atom

A [tool](/concepts/tools-and-extensions) is the unit of work: a plain Python
function you decorate, or a tool from a mounted MCP server. You clip **extensions**
onto a tool to wrap or transform it into a new variant, and you save a versioned
configuration of a tool as a [preset](/concepts/presets). Around all of this the
runtime adds [access control](/concepts/access-control),
[connectors](/concepts/connectors), [storage](/concepts/storage-and-resources),
[human-in-the-loop steps](/concepts/interactions), and
[live operation](/concepts/live-operations) — each its own pillar.

## Self-contained and yours

Every install is a self-contained system you host yourself. The same HTTP surface
drives both the `tai` CLI and any MCP client, so a server is fully operable from a
terminal as well as from a client such as Claude Desktop or Cursor.


# Quickstart
Source: https://docs.tai42.ai/getting-started/quickstart

Boot a server and call a tool over MCP.

Boot a working server from the shipped hello-world example, then list and call a
tool over MCP. The example is one local `greet` tool — no agents, no services to
stand up, nothing to configure. The server does make one outbound call of its
own: it polls the marketplace for security advisories on a timer, and
`MARKETPLACE_ADVISORIES_POLL=false` turns that off.

**1. Install the runtime**

The example ships in the `tai42` monorepo under `core/skeleton`, so run it
from a checkout — clone the monorepo and install the skeleton into a fresh
environment, as the [installation guide](/getting-started/installation)
describes:

```bash theme={null}
git clone https://github.com/tai42ai/tai42
cd tai42/core/skeleton
uv venv --python 3.13
uv pip install --no-sources --editable .
```

**2. Boot the hello example**

From the repository root, load the `examples/hello` manifest and serve it:

```bash theme={null}
ACCESS_CONTROL_ENABLE=false \
PYTHONPATH=examples/hello \
uv run --no-sync tai serve --manifest-path examples/hello/manifest.yml --port 8765
```

`ACCESS_CONTROL_ENABLE=false` turns off the request-auth gate, which is on
by default and checks every request against Redis — this example does not
use it. `PYTHONPATH=examples/hello` makes the example's `myapp` package
importable, because the manifest loads tools by import path.

Startup is chatty — most of it is the operations projection reporting which
of the server's own operations it did and did not expose. The log ends with:

```
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8765 (Press CTRL+C to quit)
```

**3. Call the tool**

The MCP endpoint is `http://127.0.0.1:8765/mcp`. From a second terminal —
inside the same checkout, because `uv run --no-sync` runs against the
environment installed there — list the tools and call `greet`:

```bash theme={null}
cd /path/to/tai42/core/skeleton
uv run --no-sync python - <<'EOF'
import asyncio
from fastmcp import Client

async def main():
    async with Client("http://127.0.0.1:8765/mcp") as c:
        print("tools:", [t.name for t in await c.list_tools()])
        result = await c.call_tool("greet", {"name": "World"})
        print("greet ->", result.content[0].text)

asyncio.run(main())
EOF
```

The first line prints the server's tool names, `greet` among them; the second
is the call result:

```
tools: [..., 'greet', ...]
greet -> Hello, World!
```

Only `greet` came from the manifest. The rest are **operation tools**: the
server projects its own management operations onto the MCP surface, and the
manifest's `api_tools` block — which governs that
projection — is on by default. Add `api_tools: {enabled: false}` to the
manifest to switch it off and leave `greet` on its own.

## What just happened

The manifest named one tool module, `myapp.tools`. Importing that module ran its
registration decorator, which registered `greet` on the server:

```python theme={null}
from tai42_contract.app import tai42_app


@tai42_app.tools.tool
def greet(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"
```

The [manifest](/concepts/manifest) is the only thing that decides what a server
loads from your app. An empty manifest (`{}`) still boots, serving the projected
operation tools and nothing of yours; adding sections adds your capabilities.

## Next steps

> **[Mental model](/getting-started/mental-model)**
>
> How the runtime fits together in one page.

> **[Concepts](/concepts/index)**
>
> One page per pillar of the platform.

> **[Build a tool](/guides/build-a-tool)**
>
> Register your own function as a tool.

> **[Connect an MCP client](/integrations/index)**
>
> Point Claude Desktop, Cursor, or any client at your server.


# Set up access control
Source: https://docs.tai42.ai/guides/access-control

Turn on the gate and write a policy.

Turn on the request-auth gate and write a jq access-control policy.
[Access control](/concepts/access-control) explains the model this configures.

The runtime gates its HTTP routes behind API keys and per-user policies. A request presents an `sk-…` key; the access-control middleware resolves the key's user and evaluates that user's jq policy against the request context. You provision keys, map routes to scopes, and attach jq conditions.

## Prerequisites

The gate is on by default. Before it can admit requests in a real deployment, these backing pieces must be in place.

**1. Access control is enabled**

The gate runs unless you set `ACCESS_CONTROL_ENABLE=false`. Leave it unset (or `true`) in production — the [quickstart](/getting-started/quickstart) disables it only for local, auth-free development.

**2. A Redis for the live auth context**

The per-user live counters live in a plain Redis — any standard `redis-server`. No RedisJSON module or `redis-stack` image is required. There is no baked-in default: point the connection with `ACCESS_CONTROL_REDIS_URL`, or let it resolve from the shared `TAI_DEFAULT_REDIS_URL` — with the gate on, one must be set, or every request that carries a key is denied. The Redis API-key provider keeps its key records in its own plain Redis, `TAI_IDENTITY_REDIS_URL`, which also falls back to `TAI_DEFAULT_REDIS_URL`.

**3. A Postgres policy store**

Scopes, route mappings, and per-user policy bodies live in Postgres — the only policy store. It lives in the [named database](/concepts/config-and-secrets#named-databases) the core `skeleton` component binds to — the `default` database unless `TAI_DB_BINDING_SKELETON` points it elsewhere. Configure that database, including its password via `TAI_DATABASE_DEFAULT_PG_PASSWORD`.

**4. An identity provider in the manifest**

The skeleton ships no concrete identity provider, so a deployment with the gate on **must** name one as a lifecycle module in the manifest. The default is the redis-backed api-key provider:

```yaml examples/access_control/identity_manifest.yaml theme={null}
# The gate ships with no concrete identity provider, so a deployment with access
# control enabled MUST name one as a lifecycle module. This is the default: the
# redis-backed api-key provider, which registers itself as the "redis" provider
# at import. ACCESS_CONTROL_AUTH_PROVIDERS (an ordered JSON list, default ["redis"]) names the chain.
lifecycle_modules:
  - tai42_identity_redis.redis_api_key_provider
```

It registers itself as the `redis` provider at import. `ACCESS_CONTROL_AUTH_PROVIDERS` (an ordered JSON list) names the chain the verifier tries; unset, the chain is every registered identity provider, sorted by name. Swap the module and the provider name to use a different authn backend.

**5. Probe routes are public by default**

A **registered, authenticated** route the operator mapped to no scope is reached by every role-holder out of the box (it resolves to the universal scope `*`); only a path the app does **not serve** is denied to ordinary identities (a condition-free `*` super-admin key is still admitted — a root is never gated by a missing route). The liveness and readiness probes carry no key, but they are served public by the app's own route-level declaration: `/health` and `/ready` ship in `ACCESS_CONTROL_ACKNOWLEDGED_PUBLIC_ROUTES`, so an orchestrator reaches them with no key and no manual pin.

## Initialize the deployment

With the gate on and no principal yet, there is no authenticated door to mint a key — `tai keys create` itself needs a key. The one-shot [`tai setup`](/reference/cli/setup) door (`POST /api/setup`) closes that gap: it creates the **owner** principal — the first admin — and mints the owner's first condition-free `["*"]` key, returned once.

```bash theme={null}
tai setup --display-name alice --token -
```

The door resolves its token in one of two ways:

* **`TAI_SETUP_TOKEN`** — an operator-set token. When set, it is the token the door expects.
* **the auto-generated token** — absent an operator token, each deployment fixes one random token once at startup and logs it a single time (`setup token: …`). Only someone who can read the server log can initialize the deployment.

Pass the token out of band, never on the command line — `--token -` reads it as one line from stdin (a value on `argv` leaks via `ps` and shell history).

The door is **one-shot and secure by default**: it refuses with `409 Already initialized` the moment any principal exists, a wrong or absent token is a generic `403` (with a per-IP backoff that escalates against a token flood), and with the gate off (`ACCESS_CONTROL_ENABLE=false`) it is disabled with a `501` — there is no deployment to initialize. For local, auth-free development, `TAI_SETUP_OPEN=true` opens the door without a token.

Once the owner key is in hand, every further key is created through the authenticated surface below.

### Initializing a deployment whose logins are OIDC

When your humans sign in through an external OIDC provider, that provider answers only **who** a caller is — it provisions nothing. An issuer-authenticated subject with no principal resolves to the empty policy, so every protected route denies it, and an OIDC identity provider mints no API keys. A fresh deployment still needs its first principal — the owner — and the setup door is the only way to create one. So the setup token matters even when every human logs in through OIDC: it guards the one door that mints the owner and the owner's first key.

Configure a **key-minting** identity provider beside the OIDC one in `ACCESS_CONTROL_AUTH_PROVIDERS` — the bundled `redis` API-key provider mints the owner's first key. The auto-generated setup token is minted and logged once, at `INFO`, only when the door can serve. No token is logged under four conditions; under the first the door still works — the token is your own value — and under the other three the door itself is unavailable and answers `501`:

* **`TAI_SETUP_TOKEN` is set** — that value is the token, and the door uses it directly.
* **no configured identity provider can mint API keys** — an OIDC-only chain mints none; add a key-minting provider.
* **the access-control Redis is unset** — the door needs it for the setup token, the throttle, and the mint lock.
* **access control is off** — there is no deployment to initialize.

The token is fixed once per deployment, so a restart finds it in place and never re-logs it. Initialize an OIDC deployment in this order:

**1. Read the setup token**

Take it from the server log, or pin it yourself with `TAI_SETUP_TOKEN`.

**2. Create the owner and first key**

Run [`tai setup`](/reference/cli/setup) — it mints the owner principal and the owner's first `["*"]` key, returned once.

**3. Sign in with the key**

The owner authenticates with that key while no interactive login exists yet.

**4. Provision the OIDC subjects**

The owner creates a principal for each OIDC subject through the admin principals door (`POST /api/auth/principals`) and grants it a role.

**5. OIDC logins work**

Each provisioned subject now signs in through OIDC; the setup door has closed for good.

On Kubernetes, pin the token ahead of boot: set `TAI_SETUP_TOKEN` from a Secret so the value is known before the pods start, rather than scraped from a replica's log.

## Provision an API key

Create a key for a user. The raw `sk-…` value is printed once — capture it then. Grant scopes with the repeatable `--scope`, and attach an inline jq authorization condition with `--condition`. A key needs at least one scope or a condition: a key with neither grants nothing, so the mint refuses it with a `400` and writes nothing — `an api key needs at least one scope or a condition: a key with neither grants nothing, and every door treats it as no key`.

```bash theme={null}
tai keys create --user alice --description 'CI key' --scope read
```

The scopes are granted with the repeatable `--scope` flag — the command's own help confirms it:

```bash examples/cli/keys_create_help.sh theme={null}
# The api-key create command grants scopes with a repeatable --scope flag.
tai keys create --help
```

The CLI itself authenticates with a key. Pass it out of band — read one line from stdin with the global `--api-key-stdin` flag, or set `TAI_API_KEY` in the environment. There is no `--api-key VALUE` flag, because a value would leak via `ps` and shell history.

### Keys for automation

A machine identity is a **service principal** — a non-human principal that holds keys but never logs in. An admin creates one, then mints keys owned by it with `--for`:

```bash theme={null}
tai principals create --kind service --display-name 'CI runner' --role editor --user ci-runner
tai keys create --user ci --description 'CI key' --scope read --for ci-runner
```

`--for` names the principal a key belongs to; omitted, a key is owned by the caller's own principal. Manage service principals with `tai principals list|disable|enable|delete`.

A principal and a key never share a user id. Creating a principal under the user id of a minted key is refused with a `409` and nothing is kept — `user id 'ci' is an api key's id; a role is assigned to a principal, never to a key`.

## Map routes to scopes

This step is for **scoped keys** — a key minted with named scopes rather than `*`. Role-holders (admin/editor/viewer and any custom role, all carrying `*`) already reach every registered route, so a fresh deployment needs **no** route-mapping step to be usable. Map a route to a named scope only to let a scoped key reach it. A scope maps URLs to a named policy target; add a URL to a scope, optionally with a dynamic match pattern, and list the current mappings.

```bash theme={null}
tai scopes add read /api/tools
tai scopes list
```

A route that declares itself public at registration answers everyone whatever scope it is mapped to, so it cannot be mapped. `tai scopes add` on a URL such a route serves, on any method, is refused with a `400` and nothing is written — mapping `/health` reads `'/health' is public by its own declaration and stays open to everyone whatever scope it is mapped to, so it cannot be mapped into scope 'read'`. `tai scopes routes` lists every route with its mapping, and its `declared_public` column is `true` for each route public by its own declaration.

The route table stores every URL in its **canonical** form — each segment percent-decoded once, repeated slashes collapsed, `.` and `..` resolved, no trailing slash — the same form every request is looked up by. `tai scopes add read /api/tools/` stores `/api/tools`, and removing or unpinning either spelling addresses the same row. A URL with no canonical form (a NUL, control or backslash byte after decoding) is refused with a `400`. An `ACCESS_CONTROL_PATH_PATTERNS` template must itself be canonical (`/studio-authed`, never `studio-authed` or `/studio-authed/`); a non-canonical template refuses the settings load, naming the form to supply. A route row that is not canonical — one written to the database directly, never through a door — stops the deployment from booting, and the refusal names every such row to correct or delete; see [access-control routes are canonical](/operate/backup-and-restore#access-control-routes-are-canonical).

> [!WARNING]
>
> **Scope a pattern to a surface; never blanket the whole site.** Every API route already declares its own protection — a scope row or pattern *adds* scoping, it is not what keeps `/api` private. Deny wins: a path that matches both a protected pattern and a public mapping resolves protected, so a whole-site pattern like `^/.*$` also matches browser page navigations and blocks the dataless Studio shell — a deep-link refresh then meets a `401` JSON body instead of the app shell and its login flow, and the shell exposes no data anyway. Tighten a real surface with a scoped pattern (`^/api/tools/.*`), never a blanket. The plugin studio-asset door stays public through its own route declaration, which the gate resolves public **alone**, ahead of any route row (a plugin bundle loads as a native ESM import that cannot send an auth header), on the methods the door serves (`GET`, and `HEAD` with it); a scope row does not protect it.

## Write and validate a jq condition

A jq condition compiles against the request context and returns whether the request is allowed. Validate one before you save it — compile it, and optionally sample-evaluate it against a `JqAuthContext`-shaped sample.

```bash theme={null}
tai keys validate-condition --condition '.method == "GET"'
```

Attach the validated condition when you create or edit a key with `--condition`.

An edit that would leave a policy with neither a scope nor a condition is refused with a `400` and nothing is written — an edit (`PUT /api/auth/api-keys/{user_id}`) that sets `"scopes": []` while no condition is set, `tai keys edit --clear-condition` on a key with no scope, or `tai keys scopes --remove` taking away the last scope of a key with no condition. The refusal names the repair for the row it refuses:

* a key reads `the edit leaves the policy with neither a scope nor a condition: a policy with neither grants nothing, and every door treats it as no key; revoke the key instead`;
* a principal's own policy reads `the edit leaves the principal's policy with neither a scope nor a condition: a policy with neither grants nothing, and every door treats it as no key; disable or delete the principal instead`;
* the last enabled admin principal's own policy is refused with the last-admin `409` instead, ahead of the `400`.

A condition that tests the path reads `.request.path`, the canonical request path: a mount prefix the app is served under is removed, segments are decoded once, slashes collapsed, dot segments resolved and a trailing slash dropped. Write path tests against that form — `.request.path | startswith("/api/tools")` — never against a decoded-but-unnormalized or mount-prefixed spelling such as `"/mnt/api/tools"` or `"/api/tools/"`; a condition written against such a spelling never matches and must be rewritten. The validator's sample verdict is the enforcer's own: `validate-condition` with a sample runs the same evaluation the gate runs.

**1. Draft the condition**

Write a jq expression over the request context and compile-check it with `tai keys validate-condition`.

**2. Attach it to a key**

Create the key with `--condition` — a templated-text JSON object carrying either inline jq (`content`) or a stored condition (`id`), plus optional render `kwargs`.

**3. Track policy changes**

Each user's enforced policy is append-only and versioned. List the history with `tai keys policy-versions`, and roll back with `tai keys policy-rollback`.

> [!WARNING]
>
> A key is revoked immediately with `tai keys delete` — the next request with it fails to authenticate. Rotate a key by revoking and re-issuing; editing a key never rotates its material.

## Verify enforcement

Prove the gate before you trust it: call a guarded route with two keys. A key whose policy grants the route's scope reaches the resource with `200`; a valid key that lacks the scope is denied with a fixed `403`. Set `TAI_BASE_URL` to your server and the `X-Api-Key` header to each key.

An allowed key reaches the resource:

```bash examples/access_control/verify_allowed.sh theme={null}
# A key whose policy grants the route's scope reaches the resource: 200.
curl -sS -o /dev/null -w '%{http_code}\n' \
  -H "X-Api-Key: $TAI_API_KEY" \
  "$TAI_BASE_URL/guarded"
```

A valid but under-scoped key is denied — a fixed `403`, with the full reason logged only server-side:

```bash examples/access_control/verify_denied.sh theme={null}
# A valid key whose policy lacks the route's scope is denied: 403.
curl -sS -o /dev/null -w '%{http_code}\n' \
  -H "X-Api-Key: $TAI_DENIED_KEY" \
  "$TAI_BASE_URL/guarded"
```

Both requests run against the real `AuthAdapter → AccessControlAuthBackend → ResourceGuardMiddleware` chain in docs CI, so a change that breaks allow/deny enforcement breaks this step.

## Delegate with owned keys

A key minted by a non-admin is an [owned key](/concepts/owned-keys) — capped at a
subset of its owner's scopes, isolated to its own data, and attenuated with the
owner on every request. To mint a capped key for a teammate or device, inspect what
it can do with `tai auth whoami`, and share it by one-time QR claim link, follow the
[owned-keys guide](/guides/owned-keys).

## See also

* [Access control](/concepts/access-control) — the key, scope, and jq policy model.
* [Owned keys](/concepts/owned-keys) — capped sub-identities, the capability
  projection, and data isolation.
* [The versioning spine](/concepts/versioning-spine) — the append-only policy history.
* [CLI reference](/reference/cli) — the full `tai keys` and `tai scopes` surface.


# Apply an extension
Source: https://docs.tai42.ai/guides/apply-an-extension

Clip an extension onto a tool.

Clip an extension onto a tool to produce a wrapped or transformed variant.

An extension is a clip-on power that wraps or transforms a tool into a new variant. Applying one branches the tool: the original stays bound, and a new `<tool>_<extension>` variant appears alongside it. You load the extension's module, then attach it to a tool — from the manifest or at runtime.

## Load the extension module

Name each extension module under `extensions_modules`. Importing the module runs its registration, adding the extension to the global catalog.

```yaml manifest.yml theme={null}
extensions_modules:
  - tai42_toolbox.extensions.cache
```

List the registered extensions to confirm the catalog:

```bash theme={null}
tai extensions list
```

## Attach it to a tool

Attach an extension in the manifest with the `extensions` map on a `tools` entry. The map is keyed by tool name; a value is one combo (`[cache]`) or a list of combos. A stacked combo `[[a, b]]` layers both onto one branch.

```yaml manifest.yml theme={null}
tools:
  - title: hello
    module: myapp.tools
    include: [greet]
    extensions:
      greet: [[cache]]
```

The `extensions` map only attaches — it never selects a tool. A mapped tool that is absent from the selected set raises loudly.

## Or attach at runtime

Apply a tool's full combo list at runtime. Each `--combo` is one combo, written as a JSON array of extension elements; repeat it to author several combos at once. An element is a bare extension name or a `{"name", "config"}` object binding author config. Passing no `--combo` clears the tool's extensions.

To change one combo without rewriting the whole list, `tai tools extensions-add` appends a single combo and `tai tools extensions-remove` drops one, leaving the tool's other combos in place — adding a combo already present is refused, as is removing one the tool does not carry.

```bash theme={null}
tai tools apply greet --combo '["cache"]'
tai tools extensions-add greet --combo '["batch"]'
tai tools extensions-remove greet --combo '["batch"]'
tai tools extensions greet
```

> [!NOTE]
>
> A **wrapper** presents the wrapped tool's input schema unchanged apart from its own control kwargs; a **transformer** presents its own composed schema. Stacked extensions apply left to right, so `[cache, batch]` produces `batch(cache(tool))`.

## See also

* [Tools and extensions](/concepts/tools-and-extensions) — the wrapper / transformer kinds and their schema rules.
* [The standard toolbox](/guides/standard-toolbox) — the shipped default extensions.
* [CLI reference](/reference/cli) — the full `tai extensions` and `tai tools apply` surface.


# Author an agent
Source: https://docs.tai42.ai/guides/author-an-agent

Author an agent against the contract.

Author an agent against the `Agent` contract and load it from the manifest.

An agent is an LLM-driven capability registered alongside tools. You implement one interface — the `Agent` contract — and the runtime derives two faces from it: a JSON `run` tool (LLM, MCP, and flow-engine facing) and an in-process `astream` method (API and SSE facing). You write only the `Agent` class; no hand-written tool wrapper.

## Implement the Agent contract

Subclass `Agent`, declare the three class attributes that drive tool generation, and implement `run`. `run` is the primitive; the base class provides a default `astream` that runs once and emits one terminal event, which streaming agents override.

```python myapp/agents.py theme={null}
from pydantic import BaseModel
from tai42_contract.agent import Agent
from tai42_contract.app import tai42_app
from tai42_contract.template import TemplatedText
from tai42_kit.utils.render import render_templated_text


class EchoInput(BaseModel):
    text: str


@tai42_app.agents.agent("echo")
class EchoAgent(Agent):
    tool_name = "echo"
    tool_description = "Echo the input text back."
    ToolInput = EchoInput

    async def run(self, *, user_message: TemplatedText | None = None, **kwargs) -> str:
        if user_message is None:
            return ""
        return await render_templated_text(user_message)
```

A message reaches `run` as a `TemplatedText` — inline `content` or the `id` of a stored resource, plus its render `kwargs` — so `run` renders it to a string through the kit's `render_templated_text` seam before using it.

`ToolInput` is a JSON-able pydantic model of the tool parameters — a non-JSON field fails loudly when its schema is generated. The `@tai42_app.agents.agent(name)` decorator registers the agent and auto-registers its JSON `run` tool.

## Load it from the manifest

Name the module under `agents[]`. Importing it runs the decorator.

```yaml manifest.yml theme={null}
agents:
  - title: my_agents
    module: myapp.agents
    include: []
```

## Run it

**1. List registered agents**

```bash theme={null}
tai agents list
```

**2. Stream a run**

Stream a run one event frame at a time, passing the input as a JSON object.

```bash theme={null}
tai agents run echo --input '{"text":"hello"}'
```

> [!TIP]
>
> Author a saved variant of an agent — an authored agent — by baking `fixed_kwargs` into a [preset](/concepts/presets) over the agent: `tai presets create`, then run it with `tai agents authored-run`. Which fields you may bake is a **per-field** capability the agent declares. Mark `spec_runnable = True` to make every `ToolInput` field bakeable, or list individual field names in `preset_bakeable_fields` to bake just those. Baking a field the agent does not declare bakeable is rejected at author time with a `400`.

## See also

* [Agents](/concepts/agents) — the two faces of one `Agent` class.
* [Deep agents](/concepts/deep-agents) — sub-agents, skills, and strategies.
* [Python SDK reference](/reference/python-sdk) — the `Agent` contract surface.


# Bring an MCP server
Source: https://docs.tai42.ai/guides/bring-an-mcp-server

Mount an external MCP server's tools.

Mount an existing external MCP server so its tools appear in your running server.

The runtime mounts other MCP servers and re-presents their tools as its own. You declare each server in the manifest's `mcp` section; the runtime probes it at startup and binds its tools alongside your local ones.

## Declare a server in the manifest

Each `mcp` entry names one server. Set exactly one transport per entry — the runtime infers the transport from whichever field you set:

* `url` for a remote HTTP or SSE server (with optional `headers`),
* `uds` for a Unix domain socket,
* `command` (plus `args` / `env`) for a stdio server the runtime launches.

```yaml manifest.yml theme={null}
mcp:
  - title: example-http
    config:
      url: https://mcp.example.com/mcp
      headers: {}
  - title: example-stdio
    config:
      command: uvx
      args: [some-mcp-server]
      env: {}
```

Use `include` / `exclude` on an entry to expose only a subset of the mounted server's tools.

## Inspect and reload

**1. Check binding status**

Snapshot the live MCP binding state — which servers attached, which were skipped by a failed viability probe, and each attached server's recent dispatch health.

```bash theme={null}
tai mcp status
```

The payload carries three blocks: `bound` maps each attached server's title to the tool names it serves, `failed` lists the servers a viability probe skipped — each entry carrying the server `title`, a coarse `status`, a `category` (`auth`, `unreachable`, or `error`), a redacted `message`, and the `http_status` the failure carried (`null` for a pure transport failure) — and `health` reports each server's most recent tool-dispatch outcome, keyed by title (a skipped server carries the block at its empty values).

```json theme={null}
{
  "bound": {
    "example-http": ["events_get", "events_list"],
    "example-stdio": ["status_check"]
  },
  "failed": [
    {
      "title": "example-sse",
      "status": "unavailable",
      "category": "auth",
      "message": "401 Unauthorized",
      "http_status": 401
    }
  ],
  "health": {
    "example-http": {
      "last_success": "2026-01-04T09:12:03.481221+00:00",
      "last_error": null,
      "consecutive_failures": 0,
      "failing_since": null
    },
    "example-sse": {
      "last_success": null,
      "last_error": null,
      "consecutive_failures": 0,
      "failing_since": null
    },
    "example-stdio": {
      "last_success": "2026-01-04T08:55:10.204118+00:00",
      "last_error": {
        "type": "ClientDisconnectedError",
        "message": "Client disconnected and was removed from the cache. Retry the operation to create a new client. (Original error: Server session was closed unexpectedly)",
        "at": "2026-01-04T09:14:22.017090+00:00"
      },
      "consecutive_failures": 3,
      "failing_since": "2026-01-04T09:13:47.902551+00:00"
    }
  }
}
```

Each `health` entry has four fields, detailed in [the `health` block reference](#the-health-block) below.

**2. Replace the set at runtime**

Write the full replacement `mcp` list to a JSON file, then apply it. This hot-reloads the section without restarting the server. `set` remains the bootstrap and restore path — use it to lay down the whole section at once.

```bash theme={null}
tai mcp set --file mcp.json
```

**3. Add or remove one entry**

Change a single server without rewriting the whole list. `tai mcp add` appends the entries in a JSON file — one entry object, a bare array, or an object carrying an `"entries"` list — and refuses a title that already exists unless you pass `--replace`, which swaps the existing entry in place. `tai mcp remove` deletes one entry by its title. Both hot-reload the section.

```bash theme={null}
tai mcp add --file entry.json --replace
tai mcp remove example-http
```

> [!NOTE]
>
> `remove` is a **persisted** change — it edits the manifest, so the server stays gone across a restart. [`deregister`](/concepts/live-operations) is a **runtime-only** detach — it drops the server's tools from the live registry but leaves the manifest untouched, so the next reload brings it back.

**4. Reload one server**

Re-probe a single server by its manifest title and re-attach it if it is viable. A successful reload also drops that server's pooled dispatch session, so the next tool call opens a fresh connection instead of reusing a stale one. A reload that finds the server unreachable reports it unavailable and leaves the session as is — once the server is back, the next tool call reconnects on its own; while it stays down, calls return the structured error described below.

```bash theme={null}
tai mcp reload example-http
```

> [!NOTE]
>
> A server that fails its viability probe is skipped, not fatal — the rest of the manifest still loads. Inspect skipped servers under `tai mcp status`.

### The `health` block

Each `health` entry has four fields:

| Field | Meaning |
| - | - |
| `last_success` | ISO-8601 time of the last completed dispatch, or `null` if the server has never served a call. |
| `last_error` | The most recent failed dispatch as `{ "type", "message", "at" }`, or `null` if none since the last success. `message` has any URL-embedded credentials redacted. |
| `consecutive_failures` | Length of the current unbroken run of failed dispatches — `0` when the last dispatch succeeded or none has run. |
| `failing_since` | ISO-8601 time of the first error in the current failure run, or `null` when the server is not currently failing. Cleared on the next success. |

`health` covers every `bound` and `failed` title. A server that has never been called carries the block at its empty values — `last_success`, `last_error`, and `failing_since` `null`, `consecutive_failures` `0`. A server that has only ever succeeded carries `last_success` with `last_error` and `failing_since` `null`. An auth-blocked dispatch records nothing: it signals credential state, not connection health, so it leaves the health block untouched. The health is this worker's own passive view — per process, so a fleet report reads each worker's dispatches separately.

## When a mounted server's tools fail

A tool call against a mounted server whose connection has dropped gets one automatic reconnect attempt. If the reconnect succeeds the call runs on the fresh session. If the server is still unavailable, the call returns a structured error whose `code` is `upstream_mcp_unavailable`, with a message that names the entry by its configured title. The raw disconnect detail never reaches that message — it is logged at the dispatch seam, not surfaced to the caller. A dispatch that fails for another reason — a transport error, a timeout, or an output-schema mismatch — returns a structured error whose `code` is `mcp_dispatch_failed`, naming the tool and the server rather than a generic `500`; the raw detail is logged and recorded on that server's `health` entry.

A mounted entry that carries a connection's reference but whose `url` is not the server its provider defines for that sub-service is refused before any credential is sent: the call fails with a message that names the entry and both repairs. Reconnecting the account (or, for a provider without sign-in, saving the connection's services again) rewrites the entry the connector wrote for that connection. Any other entry that carries the reference is not the connector's own, so a reconnect leaves it as it is and it keeps being refused until the reference is removed from it.

## See also

* [Transports](/concepts/transports) — the HTTP, SSE, stdio, and UDS paths a mounted server can use.
* [The manifest](/concepts/manifest) — the `mcp` section and its selection fields.
* [Live operations](/concepts/live-operations) — hot-reload and deregister at runtime.
* [CLI reference](/reference/cli) — the full `tai mcp` surface.


# Build a tool
Source: https://docs.tai42.ai/guides/build-a-tool

Register a Python function as a tool.

Write a plain Python function, register it, and load it from the manifest as a tool.

A tool is the atom of work — a plain Python function the runtime exposes as an MCP tool. You write the function, decorate it with `@tai42_app.tools.tool`, and name its module in the manifest. Importing the module runs the decorator, which registers the tool on the server.

## Write the tool module

Put your function in a module in your own package and register it through the `tai42_app` handle. The decorator returns the function unchanged, so the module stays ordinary Python.

```python myapp/tools.py theme={null}
from tai42_contract.app import tai42_app


@tai42_app.tools.tool
def greet(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"
```

The function's signature becomes the tool's input schema and its docstring becomes the tool description, so annotate the parameters and write a real docstring.

## Load it from the manifest

Name the module under `tools[].module`. Each entry imports the module; `include` filters which tool names to expose (omit it to expose every tool the module defines).

```yaml manifest.yml theme={null}
tools:
  - title: hello
    module: myapp.tools
    include: [greet]
```

The module must be importable from the server process, so keep your package on `PYTHONPATH`.

## Run and call it

**1. Start the server**

Point the server at your manifest and start it.

```bash theme={null}
tai serve --manifest-path manifest.yml
```

**2. Confirm it registered**

List the registered tools and inspect one tool's schema.

```bash theme={null}
tai tools list
tai tools schema greet
```

**3. Run it**

Call the tool synchronously and print its result. Pass arguments with the repeatable `--kw key=value` (each value is parsed as JSON), or a whole JSON object with `--kwargs`.

```bash theme={null}
tai tools run greet --kw name=Ada
```

> [!TIP]
>
> Long-running work does not have to block a request. Submit a detached run with `tai tools runs submit`, then poll it with `tai tools runs get`.

## Fenced tools

A tool declares a **registration tier** to mark it admin-only. Declaring the
`fenced` (or `secret`) tier gates both **authoring** a preset over the tool and
**running** it: only an administrator may run a fenced tool, and a preset authored
over one inherits the fence at run time. A tool with no declaration, or a `read` /
`write` one, carries no extra execution gate.

Declare it on the decorator:

```python theme={null}
@tai42_app.tools.tool(tier="fenced")
def run_script(argv: list[str], *, image: str) -> dict:
    """Run a command in a disposable sandbox."""
    ...
```

The fence is enforced once at the shared tool-run chokepoint, so it holds on every
door a run can enter through — the HTTP run-tool route, the MCP edge, a background
submit, a hook or schedule fire, an agent dispatch, a channel turn. A non-admin run
is refused loudly (an HTTP `403`, an MCP tool error, or a recorded failed run on a
detached door), never silently dropped. The built-in `sandbox_exec` tool declares
`fenced` for exactly this reason — running arbitrary code is an admin act.

With access control off every caller resolves as an administrator, so the fence
bites only where the platform fences at all.

## Tools that can pause

A tool that can pause — it parks, asks with `mode="async"`, or waits on a participant
out of band — declares `meta={"tai42/pauses": True}` (`TOOL_META_PAUSES` from
`tai42_contract.tools`):

```python theme={null}
from tai42_contract.tools import TOOL_META_PAUSES


@tai42_app.tools.tool(meta={TOOL_META_PAUSES: True})
async def request_approval(question: str) -> object:
    """Ask a person and pause until they answer."""
    ...
```

A tool that returns a park signal without it fails with `UndeclaredPauseError` naming it.
The refusal holds on every door that recognises a park: the HTTP run-tool route answers
`501`, the MCP edge answers a tool error, and an agent run that called the tool ends failed
rather than handing its model a tool error to retry around. A flow node awaits an undeclared
tool inside the node; a declared one pauses the run.

## See also

* [Tools and extensions](/concepts/tools-and-extensions) — what a tool is and how an extension wraps one.
* [The manifest](/concepts/manifest) — every section a server loads at startup.
* [Apply an extension](/guides/apply-an-extension) — clip a wrapper or transformer onto a tool.
* [CLI reference](/reference/cli) — the full `tai tools` surface.


# Connect an OAuth provider
Source: https://docs.tai42.ai/guides/connect-an-oauth-provider

Wire an OAuth connector end to end.

Wire an OAuth connector end to end so tools can call an authenticated third-party API.

A connector is an OAuth connection to an outside app. A connector provider is a [descriptor](/concepts/connectors) — pure data declaring the provider's OAuth endpoints and sub-services; the connector engine drives the authorize flow, stores the tokens, and launches the provider's sub-service MCP servers. This guide covers the platform flow — loading a provider, running the connect flow, and using the connection. Provider-specific setup (the OAuth app to register, the client-credential environment variables) lives in that provider's own repository README.

## Load a connector provider

A provider is registered from the manifest's `connectors:` list — the server registers each descriptor there at boot and on every reload, with no module import and no `lifecycle_modules` entry. There are two ways to add one:

* **Install it from the marketplace.** Installing a connector listing patches its descriptor into the manifest `connectors:` list for you (and takes the client credentials up front):

  ```bash theme={null}
  tai plugins install acme/connector-example \
    --env CONNECTORS_ACME_CLIENT_ID=... \
    --env CONNECTORS_ACME_CLIENT_SECRET=... \
    --secret CONNECTORS_ACME_CLIENT_SECRET
  ```

* **Add the descriptor by hand.** Put a `connectors:` entry in the manifest — the same `ProviderDescriptor` shape a listing ships:

  ```yaml manifest.yml theme={null}
  connectors:
    - id: acme
      kind: oauth
      origin: community
      category: communication
      display_name: Acme
      icon_url: https://cdn.acme.example/icon.png
      client_id_env: CONNECTORS_ACME_CLIENT_ID
      client_secret_env: CONNECTORS_ACME_CLIENT_SECRET
      oauth:
        authorize: https://acme.example/oauth/authorize
        token: https://acme.example/oauth/token
      sub_services:
        acme:
          id: acme
          display_name: Acme
          scopes: [https://acme.example/auth/acme.readonly]
          mcp_server: {type: http, url: https://acme.example/mcp}
  ```

Set the provider's client-credential environment variables on the server process — each provider names them in its README (the `client_id_env` / `client_secret_env` above). With the descriptor in the manifest and the credentials present, list the available providers:

```bash theme={null}
tai connectors providers
```

## Run the connect flow

**1. Start a connection**

Name the provider, give the connection a unique alias, and enable one or more sub-services. The command prints the authorize URL.

```bash theme={null}
tai connectors connect acme --alias work --sub-service acme
```

**2. Authorize**

Open the printed authorize URL in a browser and grant consent. The provider redirects back to the server's callback, which exchanges the code and stores the tokens under the alias.

**3. Confirm the connection**

List the installed connections (no secrets are printed).

```bash theme={null}
tai connectors connections
```

Change which sub-services a connection exposes with `tai connectors sub-services`, re-authorize with `tai connectors reconnect`, and remove a connection with `tai connectors disconnect`.

> [!NOTE]
>
> A connector provider carries no OAuth, probe, or launch code — it is pure descriptor data. The connector engine drives the whole flow generically from that descriptor.

## See also

* [Connectors](/concepts/connectors) — what a connector is and how the engine drives it.
* [Plugins](/plugins) — the shipped connector providers and their repositories.
* [CLI reference](/reference/cli) — the full `tai connectors` surface.


# Connect your own system
Source: https://docs.tai42.ai/guides/connect-your-own-system

Send messages to an agent over the authed API door and receive answers by signed callback.

Wire your own application to an agent through the conversation bridge's **API
door**: your system `POST`s a message, the bridge runs an agent turn as the route's
execution key, and the answer comes back by a signed HTTPS callback (or inline on a
bounded wait).

See [client conversations](/concepts/client-conversations) for the model.

## Two identities: who-may-send vs what-the-agent-may-do

An API route separates two authorities, and you provision both:

* **The invoking key** — the API key your system authenticates with when it `POST`s
  a message. The access-control gate authorizes it for the route's send door; it
  answers *who may send*.
* **The execution key** — the identity the turn runs **as**. Its live grants are
  the turn's entire authority; it answers *what the agent may do*.

They are independent. The sender never inherits the agent's authority, and the
agent never runs as the sender.

**1. Mint the invoking key**

A scoped key your system will send with. Scope it to reach the route and no
more.

```bash theme={null}
tai keys create --user account-app --description 'invokes the account route' --scope conversations
```

**2. Mint the execution key**

A least-privilege key the agent runs as (see [owned keys](/guides/owned-keys)).

```bash theme={null}
tai keys create --user account-agent --description 'account route agent' --scope read
```

## Create the API route

An `api` route may carry an HTTPS `callback_url` — the sink the answer is POSTed to;
this walkthrough uses one. When set, the URL **must** be absolute HTTPS; an `http://`
or relative URL is rejected at create. A route with no `callback_url` reads its answers
back from the poll door instead (below).

```bash theme={null}
tai conversations create account \
  --door api --target-name account-agent-spec --execution-key account-agent \
  --callback-url https://your-app.example.com/tai/answers
```

The response carries a **`callback_secret`** — shown **once**, here, and never
readable again. It signs every callback for this route. Capture it now and store it
where your callback receiver can read it.

```json theme={null}
{
  "created": true,
  "route_name": "account",
  "route": { "door": "api", "target_kind": "agent", "target_name": "account-agent-spec", "callback_url": "https://your-app.example.com/tai/answers" },
  "callback_secret": "shown-once-store-it-now"
}
```

## Send a message

`POST` to the send door with your invoking key. `external_user_id` is your handle
for the end user — it becomes the conversation's thread key, so the agent remembers
that user's earlier turns.

```bash theme={null}
curl -sS -X POST "$TAI_BASE_URL/api/conversations/account/messages" \
  -H "X-Api-Key: $INVOKING_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"external_user_id": "user-42", "text": "What is my usage?"}'
```

The default answer is `202` with the id to correlate the callback against:

```json theme={null}
{ "data": { "message_id": "4f1c…", "thread_id": "bridge:account:user-42" } }
```

Without a `callback_url` on the route, read the answer back once the turn finishes from
`GET /api/conversations/{route_name}/messages/{message_id}`, keyed by the `message_id`
this `202` returned.

The door refuses loudly rather than silently: `404` unknown route, `429` the
address rate cap, `503` the thread queue is full, `501` no conversations backend
configured, `400` a malformed body, `401` an unauthorized caller.

### Sync variant: `wait_seconds`

Add `wait_seconds` to wait inline for a fast turn. A turn that finishes within the
window answers `200` with the answer embedded and its callback **suppressed** (so it
never double-fires); a turn still running when the wait elapses falls back to `202`
and the answer arrives by callback as usual. A turn that finishes **silent** resolves
the same way — `200` inline with `status: "silent"` and no answer text. The window is
clamped to the deployment's `sync_wait_max_seconds` cap.

```bash theme={null}
curl -sS -X POST "$TAI_BASE_URL/api/conversations/account/messages" \
  -H "X-Api-Key: $INVOKING_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"external_user_id": "user-42", "text": "What is my usage?", "wait_seconds": 20}'
```

```json theme={null}
{ "data": { "message_id": "4f1c…", "thread_id": "bridge:account:user-42",
            "answer": { "message_id": "4f1c…", "thread_id": "bridge:account:user-42",
                        "status": "answered", "answer": "Your usage is 12 runs this week." } } }
```

## Receive the callback

The bridge `POST`s the answer to your `callback_url` as JSON. The body is the
answer payload; correlate it by `message_id`:

```json theme={null}
{ "message_id": "4f1c…", "thread_id": "bridge:account:user-42",
  "status": "answered", "answer": "Your usage is 12 runs this week." }
```

On a turn that errored, the shape is identical but `status` is `error` and `answer`
is **client-safe text** — never an internal detail the platform holds. By default it is
the generic line:

```json theme={null}
{ "message_id": "4f1c…", "thread_id": "bridge:account:user-42",
  "status": "error", "answer": "Sorry, something went wrong handling your message. Please try again." }
```

The `answer` is the first of: the failing target's own reply, when its failure carries
one; the route's `reply_texts.error`; the built-in line above. A tool target supplies its
reply on the failure it raises, and the internal outcome stays out of the answer:

```python theme={null}
from tai42_contract.app import tai42_app
from tai42_contract.interactions import RunTerminalFailed


@tai42_app.tools.tool
async def usage_report(reason: str) -> str:
    # `{"reason": ...}` is the internal outcome; `reply` is what the person reads.
    raise RunTerminalFailed({"reason": reason}, reply="That report is not available right now.")
```

The reply is text of 1 to 2,000 characters, not blank, and you own that it is safe for the
person reading it. See [failure replies](/reference/conversation-bridge#failure-replies)
for the failures that always keep the fixed text.

On a **silent** turn — a `tool` target whose mapped reply was `null` or blank, or an
ordinary inbound on a [`manual`-mode
thread](/reference/conversation-bridge#control-mode) whose suppressed target turn
produced no reply — the callback carries `status: "silent"` and **no** `answer` key at
all:

```json theme={null}
{ "message_id": "4f1c…", "thread_id": "bridge:account:user-42", "status": "silent" }
```

Every turn therefore resolves to one of `answered`, `error`, or `silent`, so your
receiver always gets a terminal callback (or inline reply) and never waits on a turn
that quietly went nowhere.

## Verify the `X-Tai-Signature`

Every callback carries an `X-Tai-Signature` header:
`sha256=<hex HMAC-SHA256(callback_secret, raw_request_body)>`. Recompute it over
the **raw** bytes and compare in constant time — reject any mismatch. This is what
proves the callback came from your deployment and was not tampered with.

```python theme={null}
import hashlib
import hmac

def verify(raw_body: bytes, header: str, callback_secret: str) -> bool:
    expected = "sha256=" + hmac.new(callback_secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)
```

> [!WARNING]
>
> Compute the HMAC over the exact bytes you received, before any JSON re-encoding —
> re-serializing the body changes the bytes and breaks the signature. Reject a request
> whose signature does not verify; never act on an unverified callback.

Delivery is retried with backoff if your receiver is down, and a permanently
undelivered answer ends `failed` (listed on `tai conversations failed`) rather than
being lost.

## See also

* [Client conversations](/concepts/client-conversations) — the delivery lifecycle.
* [Conversation bridge reference](/reference/conversation-bridge) — payload models,
  the read doors, and every setting.
* [Set up access control](/guides/access-control) — scoping the invoking key.


# Create and version a preset
Source: https://docs.tai42.ai/guides/create-and-version-a-preset

Save and evolve a configured tool.

Save a configured tool as a named preset and evolve it across versions.

A preset is a versioned, named wrap of a tool. It bakes some of a base tool's arguments as fixed constants and exposes the rest under a new name. Every preset is versioned — it rides the platform's [versioning spine](/concepts/versioning-spine), so every save appends a version, one version is active, and you can roll back. A preset is always a durable, store-backed record.

A preset body is small — a base tool and the fields to bake:

```yaml examples/presets/minimal_preset.yaml theme={null}
# A minimal preset body: base_tool and description are required; the rest carry
# sane defaults.
base_tool: echo_tool
description: Echo the input back unchanged.
```

## Create a preset

Name the base tool, a `--description` (the preset tool's LLM-facing docstring — required and non-empty on every create path), and the fixed kwargs to bake. The baked keys are removed from the exposed schema; the remaining arguments keep the base tool's real typed schema. Create writes the durable store row and then registers the live tool.

```bash theme={null}
tai presets create greet --base-tool echo --description 'Greet a user' --kwargs '{"prefix":"hi"}'
```

List presets and read one back:

```bash theme={null}
tai presets list
tai presets get greet
```

To check a draft before committing it — the same pre-write validation the create route runs, but without writing — dry-run it with `validate`:

```bash theme={null}
tai presets validate greet --base-tool echo --description 'Greet a user' --kwargs '{"prefix":"hi"}'
```

## Save a new version

Save a new version when the configuration changes. Omitted fields carry forward from the active version; `--extensions '[]'` sends the explicit clear sentinel. `description` is editable per version — pass `--description` to set new text, or omit it to carry the active one forward (it can never go empty); a rollback restores the older version's description along with the rest of its body.

```bash theme={null}
tai presets save-version greet --kwargs '{"prefix":"hey"}' --description 'Greet a user warmly'
```

Inspect the history and one version:

```bash theme={null}
tai presets versions greet
tai presets get-version greet 1
```

## Roll back

Make a prior version active again. Rollback appends a new version pointing at the target body — it never rewrites history.

```bash theme={null}
tai presets rollback greet 1
```

## Tag a version

`set-version-tags` labels an immutable version body — a per-version marker like `stable` or `reviewed` — without rebinding the tool. Passing no tags clears them to `[]`.

```bash theme={null}
tai presets set-version-tags greet 2 stable reviewed
```

These per-version tags are the only tags a preset record carries. A preset has no record-level tags, folder, or display name of its own; that organizational metadata — a display label, a folder, user tags, and visibility — lives in the [tool-organization overlay](/concepts/tool-organization), keyed by the preset's tool name and managed with `tai tool-meta`, exactly as it is for any other tool.

## Rename a preset

A preset's name is its live tool name, so renaming it rebinds the tool — the new name binds before the old is torn down. Rename integrity is enforced atomically at one gate: a rename **blocks with a `409` listing every holder** of the name until you update them. That list is the full union — the other presets that compose this one (their authored-agent specs name it as a tool) plus every behavioral holder that wires against the name (a schedule firing it, a hook or conversation route targeting it, a tool-extensions entry, a parked interaction's resume continuation, or a plugin-held reference). Display metadata is not a holder: the [tool-organization overlay](/concepts/tool-organization) follows the name across the rename. Preflight with `referees`, then rename:

```bash theme={null}
tai presets referees greet
tai presets rename greet greeter
```

> [!NOTE]
>
> The versioning spine is one mechanism, shared by many kinds. Presets, access-control policies, and authored agents all ride it — append-only versions, an active pointer, rollback, per-version tags, and rename over an opaque body.

The full subcommand set — including `validate`, `referees`, `set-version-tags`, and `rename`:

```bash examples/presets/presets_help.sh theme={null}
# The presets group carries the versioned-preset workflow plus the newer
# referees / validate / set-version-tags / rename subcommands.
tai presets --help
```

## See also

* [Presets](/concepts/presets) — what a preset is and how binding works.
* [The versioning spine](/concepts/versioning-spine) — the shared append-only version model.
* [Author an agent](/guides/author-an-agent) — an authored agent is a preset over a spec-runnable agent.
* [CLI reference](/reference/cli) — the full `tai presets` surface.


# Fire a tool from a webhook
Source: https://docs.tai42.ai/guides/fire-a-tool-from-a-webhook

Bind a tool to an inbound webhook.

Bind a tool to an inbound webhook behind a verifier and a condition filter.

The runtime fires a tool when a signed webhook arrives. A hook binds a topic to a tool; a verifier authenticates each delivery over its raw bytes before the payload is parsed; an optional condition filters which deliveries fire the tool. This guide covers the platform wiring — the hook, the verifier binding, and the filter. Provider-specific signature schemes live in that verifier plugin's own repository README.

> [!NOTE]
>
> An event that belongs to an existing **conversation** goes through the [event
> door](/reference/conversation-bridge#the-event-door), not a hook: it enters that thread
> as a turn on the conversation's own FIFO, rather than firing a **detached** tool run
> with no thread. Use a hook when the event is standalone; use the event door when it must
> be ordered and answered inside a live conversation.

## Register a hook

A hook names the topic to listen on and the tool to fire. Register it from a `HookParams` JSON body. Add a `condition` (a jq expression over the delivery) to fire the tool only on matching deliveries.

```bash theme={null}
tai hooks register --params '{"name":"deploy-notify","topic":"github","tool":"notify"}'
```

The `name` and `topic` must each be a single URL-safe path segment —
`^[a-z0-9][a-z0-9_-]*$` (lowercase letters, digits, underscores, and hyphens, opening
on a letter or digit). The topic becomes a segment of the public
`/universal_webhook/{topic}` URL, so a dot, slash, uppercase letter, or space is
rejected at registration with a `400`.

List the registered hooks:

```bash theme={null}
tai hooks list
```

## Bind a verifier to the topic

An inbound webhook door is public — bind a verifier so every delivery on the topic is signature-verified before the tool fires. Name a registered verifier and pass its per-binding config. Verification fails closed: a signature failure rejects the delivery and the tool never runs.

```bash theme={null}
tai hooks set-verifier github --verifier shared_secret --config '{"header":"X-Hub-Signature","secret_env":"GITHUB_WEBHOOK_SECRET","id_header":"X-GitHub-Delivery"}'
```

The verifier config never holds a secret value — only the name of the environment variable that holds it, resolved at verify time. `shared_secret` also requires an `id_header` naming a header the sender fills with a unique per-delivery id; the ingress dedupes on it to refuse replays, so a binding without it fails closed.

**1. Load the verifier**

A verifier registers when the manifest imports its module. Load the built-in shared-secret verifier — or a provider verifier package — under `lifecycle_modules`.

```yaml manifest.yml theme={null}
lifecycle_modules:
  - tai42_skeleton.webhooks.builtin.shared_secret
```

**2. Register the hook**

Bind the topic to the tool with `tai hooks register`.

**3. Bind the verifier**

Lock the topic's door with `tai hooks set-verifier`. Remove a binding with `tai hooks delete-verifier`.

> [!WARNING]
>
> A topic with no verifier bound accepts unauthenticated deliveries — the door is open. Bind a verifier to any topic reachable from the internet. A body-signature verifier rejects GET delivery, so the raw payload cannot ride the URL unauthenticated.

## Trigger links (QR)

A **trigger link** is a minted, public URL — `GET /trigger/<token>` — that resolves to a hook topic and fires its registered hooks, exactly as the ingress door does. The token in the path *is* the capability: whoever holds the URL fires the topic. Print the URL as a **QR code** — a picture of the URL — on a wall, a sticker, or a slide, and every scan fires the topic. A link is **timed** (you pick the lifetime in seconds; the store expires it) or **permanent**, and **revocable** by name at any moment.

Trigger links belong to the hooks surface: any role granted hooks `write` mints and revokes them; hooks `read` lists them.

A fire runs the topic's hooks as the link's execution key. If that key is revoked, a
fire is still answered `200`, and its hook run is held as failed with `unauthorized`
(see [When a hook run fails](#when-a-hook-run-fails)).

### Mint a link and fire it

Mint a timed link for a topic. Exactly one of `--ttl SECONDS` or `--permanent` is required — expiry is an explicit choice, with no default:

```bash theme={null}
tai hooks create-trigger-link events --ttl 3600
```

The command prints the absolute URL and the expiry. Present that URL as a QR; a scan is a bare `GET`, so a scan fires the topic:

```bash theme={null}
curl https://your-host.example/trigger/trg-<token>
```

Every miss answers the *same* `404` — an unknown, expired, or revoked token, or a topic that has since gained a verifier, are all indistinguishable, so the public door gives no oracle to probe. A successful response never names the topic either: the URL holder fires a topic without learning which one.

Mint a link that never expires with `--permanent`, and name it so you can revoke it later:

```bash theme={null}
tai hooks create-trigger-link events --permanent --name daily-digest
```

Carry per-link tool arguments with `--params` (a JSON object). They are merged into every hook the link fires, so one hook can back many QRs, each with different inputs:

```bash theme={null}
tai hooks create-trigger-link events --ttl 3600 --params '{"flow_graph_kwargs": {"region": "eu"}}'
```

Revoke a link by name — immediate and durable:

```bash theme={null}
tai hooks delete-trigger-link daily-digest
```

### What reaches the tool

Each fired hook runs its tool with a **shallow, top-level merge** of three sources, strongest last:

1. the hook's `start_expr` output over the scan payload (weakest — the scan influences it),
2. the link's `--params`,
3. the hook's static `tool_kwargs` (strongest — a pin the link cannot override).

A scan's query string reaches the tool **only** when the hook opts in with a `start_expr` that maps it. Register a hook whose `start_expr` lifts `?name=` into the tool input:

```bash theme={null}
tai hooks register --params '{"name":"greet","topic":"events","tool":"notify","start_expr":{"content":"{who: .name}"}}'
```

Now `GET /trigger/<token>?name=Ada` fires `notify` with `{"who":"Ada"}` — unless the link's `--params` or the hook's static `tool_kwargs` also set `who`, which win over the scanned value.

> [!WARNING]
>
> **Treat the URL — and its QR — as a capability.** Anyone who holds it fires the topic, for as long as the link lives. Revoke on any leak, and "leak" is broader than a copied link: the token rides the URL **path**, so it lands in reverse-proxy and server **access logs** — a log reader gains fire-capability. Automated URL fetchers leak it by *firing* it: chat and mail **link-preview unfurlers** and security scanners issue exactly the bare `GET` that fires the link, so pasting the URL into a chat can fire the topic before a human ever scans it. Mitigate with short `--ttl` and prompt revocation.

> [!WARNING]
>
> **Verified topics and trigger links are mutually exclusive, both ways.** Minting a link for a verifier-bound topic is refused, and a link fired against a topic that *gained* a verifier after minting answers the uniform `404`. A trigger link is unauthenticated; routing it into a signature-verified topic would silently bypass that guarantee. If you need both, use two topics.

> [!NOTE]
>
> **The token is shown once**, in the create response. It is never stored and cannot be listed or re-read — a listed link's QR is unrecoverable by design. To rotate a code, revoke the link and create a new one.

> [!WARNING]
>
> **Revoking a link does not close the topic.** The topic name itself stays firable through `POST /universal_webhook/<topic>` regardless of any link's state — revocation kills the *token*, not the topic. Choose **unguessable topic names** for trigger-linked topics.

> [!WARNING]
>
> **Link params reach every hook on the topic.** The `--params` fan out per event to *all* hooks bound to the topic, including hooks registered later by anyone holding hooks `write`. If a link carries sensitive params, mind who holds hooks `write` on that topic.

### Rate limits and merge behavior

The public `/trigger/<token>` door is **rate-limited** from the start — a public door must not ship without flood control. It is the `trigger` family, held at 60 requests a minute and 10 in any 10 seconds; over the limit answers `429`. [Flood control on public doors](/concepts/access-control#flood-control-on-public-doors) covers the budgets and how to tune them.

The bucket is **per client address**. Two facts follow for a shared wall QR:

* A crowd behind one NAT shares a single budget — the 11th scan in 10 seconds from behind that NAT gets a `429`.
* Behind a reverse proxy with no proxy trust declared (the default), *every* scanner collapses into the proxy's single peer-address bucket. For crowd-scale deployments declare the proxy — `TAI_RATE_LIMIT_TRUSTED_PROXIES` (addresses or CIDR blocks) or `TAI_RATE_LIMIT_TRUSTED_HOPS` (a hop count) — and raise the `trigger` family's budget.

Two more behaviors to know:

* **Params merge as a shallow, whole-value replace.** A link's `flow_graph_kwargs` replaces the hook's *entire* `flow_graph_kwargs` value — there is no deep merge of nested keys.
* **Revocation survives a backup restore.** A revoked link stays dead even after its record is restored from a backup, so restoring an old backup cannot re-arm a link you already revoked.

### Manage links in the Studio

The Studio's hooks page carries a trigger-links section: a table of live links (name, topic, expiry, a params indicator, and the token's hash prefix) each with a revoke-confirm, plus a **Create trigger link** button. The create flow takes a topic, an optional name, an expiry (permanent, 1 hour, 1 day, 7 days, or custom seconds), and an optional params JSON. On success a dialog renders the **QR code** with a copy field for the URL and a shown-once caption — revoke and re-create to get a new code.

![The Studio hooks page create-trigger-link dialog showing the generated QR code.](https://mintcdn.com/tai42/iRrtHiBZz_SZ94au/images/studio/hooks-trigger-link-light.png?fit=max\&auto=format\&n=iRrtHiBZz_SZ94au\&q=85\&s=9f020fe30e53850f18f6ba5270a7feab)

Creating a trigger link on the Studio hooks page — the QR is shown once.

## When a hook run fails

A run that cannot finish is held as failed, and you get an operator notification.
List the failed runs:

```bash theme={null}
tai hooks runs list --status failed
```

Fix the cause — the hook, its tool or its execution key — then retry the run, or
discard it:

```bash theme={null}
tai hooks runs retry <id>
tai hooks runs discard <id> --yes
```

The `acted` column says whether and how the hook had already acted:

| `acted` | What a retry does |
| - | - |
| `start` | replays the tool's start, with the same input and the same idempotency key |
| `""` or `cancel` | runs the hook again |
| `resume` or `take` | nothing: the run can only be discarded |

A failed run that still shows a `claim_intent` was stopped in the middle of a claim on
an entry that was resolved by then. Its `last_error` says the platform cannot tell who
resolved it; a retry runs it as a fresh run. See [Kept and
retried](/concepts/hooks#kept-and-retried) for what is retried on its own and what is
held.

## See also

* [Triggers and webhooks](/concepts/triggers-and-webhooks) — the hook and verifier model.
* [Interactions](/concepts/interactions) — external human-in-the-loop answers arrive through the same callback machinery.
* [`tai hooks` reference](/reference/cli/hooks) — the full command surface, including the trigger-link commands.
* [Share an owned key by QR claim link](/guides/owned-keys#share-it-by-qr-claim-link) — the other QR in the platform, and the opposite job: a claim link logs a device **in**, a trigger link fires a **topic**.
* [CLI reference](/reference/cli) — the full `tai` surface.


# Guides
Source: https://docs.tai42.ai/guides/index

Task-shaped how-to guides.

Task-shaped how-to guides for using the platform.

> **[Build a tool](/guides/build-a-tool)**
>
> Register a Python function.

> **[Author an agent](/guides/author-an-agent)**
>
> Author against the contract.

> **[Connect an OAuth provider](/guides/connect-an-oauth-provider)**
>
> Wire a connector end to end.

> **[Run a server](/operate)**
>
> Self-host, deploy, and operate — in Operate.

> **[The standard toolbox](/guides/standard-toolbox)**
>
> The shipped default set.


# Link a person across channels
Source: https://docs.tai42.ai/guides/link-a-person-across-channels

Pair a person's addresses on different channels into one conversation with a single-use code.

One person often reaches an agent from more than one place — a Telegram chat, a
WhatsApp number, a web session. **Person linking** pairs those addresses so they
share one conversation: after linking, every paired channel keys the same
[`bridge:@person:{person_id}` thread](/concepts/client-conversations#conversation-lifetime),
and the agent remembers the person across all of them rather than treating each
address as a stranger.

Linking is proven, never guessed: the person shows, from a second channel, a
single-use code minted on the first. Nothing is inferred from names or numbers.

## Turn on multichannel for the target

Linking is opt-in per target. Enable it on the agent or tool a route points at:

```bash theme={null}
tai conversations config-set agent assistant --multichannel
```

With multichannel **off**, the pairing commands below are ordinary text passed
straight through to the target, and the `get_pairing_code` tool refuses — the reach
is bounded so a target never links people unless its operator asked for it.

You can also set a first-contact greeting that hands a newcomer a code to pair with,
by referencing the `{pairing_code}` placeholder — it is filled with a fresh code on
first contact:

```bash theme={null}
tai conversations config-set agent assistant --multichannel \
  --greeting-template 'Hi! To link another channel, send this code there: {pairing_code}'
```

## Mint a code

A code is a single-use token of the shape `LINK-XXXXXXXX`. There are three ways to
mint one for a live conversation:

* **The `/link` command.** The person sends exactly `/link` to the conversation;
  the turn engine mints a fresh code and replies with it. (`/link` matches only as
  the whole message — `/link` with anything after it is ordinary text.) The reply
  is the route's `reply_texts.pairing_code` template when it sets one
  (`{pairing_code}` the code, `{expires_at}` its expiry), else the built-in
  sentence.
* **The first-contact greeting**, if it carries `{pairing_code}` as above.
* **The `get_pairing_code` tool**, for a programmatic mint. It takes the `channel`,
  the route's `our_identity`, and the `sender` address to link, and returns
  `{code, expires_at}` and nothing else — the raw code once, never stored
  recoverably. Composing the invite around it (a typed code, or a
  [channel-web](/plugins/tai42/channel-web) `?tai_pair=` URL) is yours to do.

Minting again for the same conversation **rotates out** the previous code — the
newest code wins, and the old one stops redeeming.

## Redeem it from the other channel

From a **different** channel, the person sends the code to the same agent. It
redeems when the `LINK-XXXXXXXX` token appears anywhere in the message — typed on
its own, pasted inside a sentence, or carried by a channel-web `?tai_pair=` link. If a
message carries more than one code, the first wins. Redeeming merges the two
addresses into one person, and from then on both channels share the one thread.
The person kept is the one created first; the other is absorbed into it.
Erasing the kept person later (`tai conversations delete-person`) also erases what the
absorbed person kept before the link: the chats it had on its own channels before the link,
with their declared state, and its own linked thread when it had one. A chat someone
continued after the link, and a chat another person also wrote in before the link, are left
until their retention period. See [forgetting a
person](/reference/conversation-bridge#forgetting-a-person).

A redeem that meets a person being erased links nothing:

* While the person who sent `/link` is being erased, the redeem answers "This conversation
  can't be linked right now. Please try again in a moment with a new code: send /link in
  your other conversation." (the route's `reply_texts.pairing_link_unavailable` when it sets
  one), and the code is used up.
* While the person redeeming is being erased, the redeem answers the route's error text
  (`reply_texts.error`, by default "Sorry, something went wrong handling your message.
  Please try again."), and the code is not used up.
* A redeem already under way when the erase of the person redeeming starts answers the
  link-unavailable text above, with the code used up. If that erase finishes before the link
  is made, the redeem answers the route's error text, the code is used up, and sending it
  again answers "That pairing code is not valid. It may have expired or already been used."

## Unlink

To detach the sending address from its person, the person sends exactly `/unlink`
from that channel. It affects only the address it was sent from.

While the person is being erased, `/unlink` answers the route's error text
(`reply_texts.error`, by default "Sorry, something went wrong handling your message. Please
try again."), and nothing is unlinked. An `/unlink` already under way when the erase starts
answers "This conversation can't be unlinked right now. Please try again in a moment." (the
route's `reply_texts.pairing_unlink_unavailable` when it sets one), and nothing is
unlinked.

## See also

* [Client conversations](/concepts/client-conversations) — the person thread and the bridge model.
* [Conversation bridge reference](/reference/conversation-bridge) — the `person_id` / `person_addresses` payload keys and every setting.
* [WhatsApp to an agent](/guides/whatsapp-to-agent) — bridging a channel to an agent in the first place.


# Manage stored content and templates
Source: https://docs.tai42.ai/guides/manage-stored-content

Store, list, and load resources.

Store, list, and load resources and templates, including media in and out.

The runtime stores content behind a storage provider and loads it through the resource manager — by storage id, by URL, or from a raw file, as text or as media. A template is one kind of stored resource: content the runtime renders with kwargs. This guide covers managing that content from the CLI.

## Wire a storage provider

Storage is dead by default — the skeleton ships no provider. Name a provider module in the manifest to turn the storage surface on:

```yaml examples/storage/storage_provider_manifest.yaml theme={null}
# Wire a storage provider by naming its module in the manifest. Storage is dead by
# default — with no storage_module the /api/storage doors answer a 501 and the
# Studio Templates screen reports the surface as unavailable. The concrete
# provider (a filesystem or object store) ships as a separate plugin package.
storage_module: tai42_storage_local
```

The concrete provider (a local filesystem or an object store) ships as a separate plugin package. With none wired, `tai storage info` reports the empty state and every CRUD door answers a `501`.

The local filesystem provider, `tai42_storage_local` (the `tai42-storage-local` package), has no default root: the deployment must set `STORAGE_LOCAL_ROOT_PATH` to the directory it serves (a relative path resolves against the server's working directory). Until it is set, every call that lists, stats, reads, writes, or deletes stored content is refused — `tai storage list`, `stat`, `upload`, `download`, and `delete` among them: the server logs `local storage is not configured: set STORAGE_LOCAL_ROOT_PATH to the storage root directory.` and an HTTP caller gets a `500`. `tai storage info` reads no content, so it still reports the provider as present. The platform container image sets `STORAGE_LOCAL_ROOT_PATH` to `/app/templates`, so a deployment from the image serves that directory unless it sets another root.

## The raw resource surface

`tai storage` is the raw provider-resource surface — upload, list, stat, download, and delete resources by id:

```bash theme={null}
tai storage upload notes/todo.txt --text 'buy milk'
tai storage list
tai storage stat notes/todo.txt
tai storage download notes/todo.txt
```

Upload takes exactly one of `--text` (stored verbatim) or `--base64` (decoded to bytes); an existing id is overwritten. A resource id must be a relative path with no `..` segment. The full subcommand set:

```bash examples/storage/storage_help.sh theme={null}
# The storage group inspects and mutates the active storage provider's resources:
# info / list / stat / download / upload / delete / delete-dir.
tai storage --help
```

## Upload and list templates

Upload a local file as a template under a key, then list what is stored.

```bash theme={null}
tai templates upload prompts/greeting.md --file greeting.md
tai templates list
```

Read one back with its input schema:

```bash theme={null}
tai templates get prompts/greeting.md
```

## Render a template

Render a stored template by `id`, or inline `content`, as one `--text` JSON object carrying the source plus any render `kwargs` (read it from a file or stdin with `--text-file` to keep a secret off the command line).

```bash theme={null}
tai templates render --text '{"id": "prompts/greeting.md", "kwargs": {"name": "Ada"}}'
```

Clear the render cache after changing a template out of band:

```bash theme={null}
tai templates clear-cache
```

The clear fans out **fleet-wide** over the [worker bus](/concepts/worker-bus) — it
evicts the compiled-template cache on every worker and returns a per-worker
`fanout` report, so a worker it could not reach is named rather than left stale.
You only need it for an **out-of-band** edit made directly on the provider side:
a template write or delete through the platform's own surface already evicts every
worker automatically.

## Load content in and out

The resource manager loads content by storage id or URL and returns it as text or media. To load a stored resource or a URL from within a tool run, enable the file-loader built-in tool, which returns a file's content as text or media:

```yaml manifest.yml theme={null}
tools:
  - title: file-loader
    module: tai42_skeleton.tools.builtin.file_loader
```

The resource-management capabilities — `upload_template`, `get_resource_by_id`, and `list_resources` — are [operations](/concepts/live-operations). Each is always a route and a CLI command, and projects as an MCP tool when [`api_tools`](/concepts/manifest#the-api_tools-block) allows it, so a tool run or an MCP client reaches the same surface the CLI does:

```bash theme={null}
tai resources get prompts/greeting.md --kw name=Ada
```

`get_resource_by_id` takes a `resource_id` and optional render kwargs; with no kwargs it returns the loaded content as-is, and with kwargs (any object, including `{}`) it renders text as a Jinja template, refusing media with a `400`. `list_resources` answers `{"resources": [...]}` — the sorted resource ids from the active provider — and `upload_template` takes a `path` and returns `{"path", "uploaded": true}`.

> [!NOTE]
>
> The storage provider is a plugin, so where content lives is swappable. The text and media surfaces are the same regardless of backend — a text-only backend satisfies the binary surface through built-in bridging.

## See also

* [Storage and resources](/concepts/storage-and-resources) — the resource manager and the load-by-id / URL / file paths.
* [Config and secrets](/concepts/config-and-secrets) — selecting the storage provider.
* [CLI reference](/reference/cli) — the full `tai templates` surface.


# One bot, many skills
Source: https://docs.tai42.ai/guides/one-bot-many-skills

Point a conversation route at a relay deep agent that delegates each message to a specialist sub-agent.

Give a single WhatsApp number, Telegram bot, or Slack app many skills by routing it
to a **deep agent** that relays each message to a specialist sub-agent. The bridge
wiring is unchanged from the other how-tos — only the agent behind the route
changes.

## Why a deep agent

An agent-target conversation route runs one **registered** agent by name, and its
turn is that agent's `astream`. To fan a single conversation out to several skills,
the routed agent must be able to delegate — which is exactly what a
[deep agent](/concepts/deep-agents) does: it plans and calls **sub-agents** as its
skills.

The plain `tools_agent` cannot: its input schema omits `subagents` and rejects them
loudly (`extra="forbid"`, plus a defense-in-depth raise on both faces). Reach for a
deep agent when one bot needs many skills.

## Configure the specialists

The only thing you author is the **roster of specialists** — each a name, a
`description` the relay agent routes on, a `system_prompt`, and the `tools` that
specialist may use. This is a `DeepSubAgentSpec` roster:

```json theme={null}
[
  {
    "name": "account",
    "description": "Questions about the user's account and profile.",
    "system_prompt": {"content": "You are the account specialist. Answer only account questions."},
    "tools": ["lookup_account"]
  },
  {
    "name": "tech-support",
    "description": "Troubleshooting a device or connection.",
    "system_prompt": {"content": "You are the technical-support specialist. Walk the user through fixes."},
    "tools": ["run_diagnostic"]
  }
]
```

Bake that roster into a small deep-agent-backed agent registered under a route-able
name. The agent is a thin authored wrapper — the roster is its whole configuration:

```python relay_agent.py theme={null}
from tai42_agents.langchain_deep_agent.agent import DeepAgent
from tai42_agents.langchain_deep_agent.tool_spec import DeepSubAgentSpec
from tai42_contract.agent import Agent
from tai42_contract.app import tai42_app
from tai42_contract.template import TemplatedText

_SPECIALISTS = [
    DeepSubAgentSpec(
        name="account",
        description="Questions about the user's account and profile.",
        system_prompt=TemplatedText(content="You are the account specialist. Answer only account questions."),
        tools=["lookup_account"],
    ),
    DeepSubAgentSpec(
        name="tech-support",
        description="Troubleshooting a device or connection.",
        system_prompt=TemplatedText(content="You are the technical-support specialist. Walk the user through fixes."),
        tools=["run_diagnostic"],
    ),
]

_deep = DeepAgent()


@tai42_app.agents.agent("relay")
class RelayAgent(Agent):
    tool_name = "relay"
    tool_description = "Relay that routes each message to a specialist sub-agent."
    ToolInput = DeepAgent.ToolInput

    async def run(self, *, user_message: TemplatedText | None = None, thread_id: str | None = None, **_: object) -> str:
        return await _deep.run(user_message=user_message, thread_id=thread_id, subagents=_SPECIALISTS)
```

> [!NOTE]
>
> A deep agent nests **one level** of sub-agents — a sub-agent may not itself declare
> sub-agents. Each specialist's `tools` are ordinary client tools the deployment has
> loaded, so the specialist can only use what the turn's execution key is also allowed
> to run.

## Load it and route to it

Name the module under `agents[]` — importing it registers `relay` — and enable the
[deep-agent module](/concepts/deep-agents) it builds on.

```yaml manifest.yml theme={null}
agents:
  - title: langchain-deep-agent
    module: tai42_agents.langchain_deep_agent
    include: [langchain_deep_agent]
  - title: relay
    module: myapp.relay_agent
```

Point any conversation route at `relay` — the channel and execution-key wiring is
exactly as in the other guides:

```bash theme={null}
tai conversations create chat-line \
  --door channel --target-name relay --execution-key chat-bot \
  --channel twilio --identity whatsapp:+14155238886
```

Now one number answers account and tech-support questions, each handled by its
specialist, with one shared conversation thread per client.

## See also

* [Deep agents](/concepts/deep-agents) — the sub-agent model.
* [Author an agent](/guides/author-an-agent) — the authoring surface used above.
* [WhatsApp to an agent](/guides/whatsapp-to-agent) — the full channel + key setup.
* [Client conversations](/concepts/client-conversations) — how a route runs its
  agent.


# Use owned keys
Source: https://docs.tai42.ai/guides/owned-keys

Mint a capped key, inspect what it can do, and share it by QR claim link.

An [owned key](/concepts/owned-keys) is a capped sub-identity you hand to a
teammate, a device, or a machine — it can never out-scope you, and it loses power
the moment your own does. This guide mints one, checks what it may do, and moves it
onto another device with a one-time QR claim link.

## Prerequisites

[Access control](/guides/access-control) is on, and you are signed in to an
[account](/concepts/accounts). As a non-admin owner, your credential is your login
session: the [Studio](/studio/login) sign-in, or, for the CLI, the session token. Your
own scopes are the ceiling for what you can delegate, and you may grant only scopes you
hold yourself. An admin may use its admin key instead, and may also mint keys for a
service principal. A non-admin's key is itself an owned key, so it can never mint. Point
`TAI_SERVER_URL` at your server and `TAI_API_KEY` at your session token (the CLI reads
both from the environment). The CLI has no sign-in command of its own: the session token is
what your accounts provider's sign-in returns. `GET /api/login/methods` lists the provider's
sign-in methods and where each one submits; with the
[Postgres accounts provider](/plugins/tai42/accounts-postgres#login), a password sign-in —
`POST /api/login/password` with your `email` and `password` — returns it as `data.token`.

## Mint a capped key

Mint a key owned by you. A non-admin owner may grant only a **subset** of its own
scopes — the new key is automatically owned by the minter, and the raw `sk-…` value
is returned exactly once, so capture it then.

```bash examples/owned_keys/mint_owned_key.sh theme={null}
# An owner mints a capped key with its login session ($TAI_API_KEY holds the session
# token). A non-admin owner may grant only scopes it holds itself, and the new key is
# owned by the minter — the raw sk-… value is returned once.
capped=$(curl -sS -o /dev/null -w '%{http_code}' -X POST "$TAI_BASE_URL/api/auth/api-keys" \
  -H "X-Api-Key: $TAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"user_id": "field-scanner", "description": "read-only field key", "scopes": ["read"]}')

# Asking for a scope the owner does not hold is rejected at mint time: a fixed 400,
# never a silently narrowed key.
excess=$(curl -sS -o /dev/null -w '%{http_code}' -X POST "$TAI_BASE_URL/api/auth/api-keys" \
  -H "X-Api-Key: $TAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"user_id": "over-reach", "description": "over-scoped key", "scopes": ["read", "write"]}')

echo "capped=$capped excess=$excess"
```

Asking for a scope you do not hold yourself is rejected at mint time with a fixed
`400` — the key is never silently narrowed to fit. From the Studio, the same mint
lives on the API-keys tab of the [Settings](/studio/api-keys) screen, where the
scope picker is capped to your own scopes.

> [!NOTE]
>
> Ownership is exactly one level deep: an owned key can never itself mint keys. An
> admin may also mint a key for a service principal. See
> [accounts](/concepts/accounts) for who may mint what.

## Inspect what the key can do

A scoped key needs to know its own limits. `tai auth whoami` prints the caller's
[capability projection](/concepts/owned-keys) — the routes, tools, and agents it
can reach right now and its effective scopes, plus a `mintable` flag. Run it with
the owned key (point `TAI_API_KEY` at the key you minted; the example keeps it in
`TAI_OWNED_KEY`):

```bash examples/owned_keys/whoami.sh theme={null}
set -e
# Run as the owned key: $TAI_OWNED_KEY holds a key the owner minted.
# `tai auth whoami` prints the caller's derived capability projection — the routes,
# tools, and agents this key can reach right now. (`mintable` is the deployment's
# flag, not this key's: an owned key still gets a 403 on any mint.)
TAI_API_KEY="$TAI_OWNED_KEY" tai auth whoami

# The same projection straight from the HTTP door the CLI wraps.
curl -sS -H "X-Api-Key: $TAI_OWNED_KEY" "$TAI_BASE_URL/api/auth/me"
```

The projection is derived from the same store and policy the gate reads and is
jq-exact, so it never lists a door the gate would then deny. It is also what the
scoped Studio renders from — a limited key sees only the features it can reach.

The `mintable` flag is not a per-caller grant: it reports whether this
**deployment's** identity provider can mint keys at all (a validator-only provider
reports `false`). An owned key can never mint regardless — it sees `mintable: true`
under a mint-capable provider yet still gets a `403` on any mint, because ownership
is exactly one level deep.

## Watch it die with the owner

An owned key never has to be revoked on its own — it is capped by its owner's
*current* policy on every request, so attenuating the owner attenuates the key on its
very next call. Prove the mechanism end to end: disable the owner or empty the owner's
scopes, then make any call with the owned key. The gate re-evaluates the key against
the owner's now-empty standing and denies it with a `403` — the key is powerless while
the owner is down, and recovers the instant the owner is restored. Deleting the owner
principal is the final lever: every key it owned then fails to authenticate at all
(`401`) and does not come back. (Revoking the owned key itself works the same way for
that one key.) The owner is a principal, not a key: revoking one of the owner's own
keys changes nothing for the keys it owns. This is why you disable or delete a person
once, rather than chasing down every key they were ever issued.

## Share it by QR claim link

To move a key onto another device without ever putting the secret in a URL, mint a
**one-time claim link**. Its token rides the URL fragment (`/login#claim=<token>`),
so it never reaches a server log, and the first exchange burns it.

```bash examples/owned_keys/claim_link.sh theme={null}
set -e
# 1. Mint a one-time claim link that carries a key you own to another device.
#    The token rides the URL fragment (/login#claim=<token>) and is single-use.
token=$(tai keys claim-link "$TAI_OWNED_KEY" --json \
  | python3 -c 'import json, sys; print(json.load(sys.stdin)["token"])')

# 2. On the other device, exchange the token for the key — a public, credential-free
#    door. `tai auth claim` accepts the bare token or the whole claim URL.
claimed=$(tai auth claim "$token" --json \
  | python3 -c 'import json, sys; print(json.load(sys.stdin)["user_id"])')

# 3. The link is single-use: exchanging the same token again is refused with a uniform
#    404 (a used, unknown, or expired token are indistinguishable to the caller).
if tai auth claim "$token" >/dev/null 2>&1; then second="reused"; else second="refused"; fi

echo "claimed=$claimed second=$second"
```

You may create a claim link only for a key you own (or, as an admin, any key); the
submitted key is validated before the link is stored, so a bad key fails fast rather
than producing a dead QR. Compose the absolute URL — or render a QR — from your own
origin and the returned `claim_path`, then open it on the other device: the
[sign-in page](/studio/login) recognises the `#claim=` fragment and exchanges the
token for the key automatically.

> [!WARNING]
>
> The link is **single-use** and short-lived. A used, unknown, or expired token all
> answer the same `404` — deliberately indistinguishable, so the public exchange door
> gives an attacker no oracle to probe. There is no way to list or revoke a claim in
> flight: wait out the TTL, or revoke the underlying key (the exchange then refuses to
> hand out a revoked credential).

## Grant scopes safely

Isolation makes some read scopes safe to grant to an owned key and leaves others
operator-only. A restricted key sees only its own tool runs, interactions, and
notifications, so those read scopes are safe. **Never** grant an owned key the
observability, storage, presets, or schedules scopes — those surfaces are
account-wide and unowned. The full table is in the
[owned-keys scope doctrine](/concepts/owned-keys#scope-doctrine).

## See also

* [Owned keys](/concepts/owned-keys) — the delegation model, the projection, and
  isolation.
* [Set up access control](/guides/access-control) — the gate, scopes, and jq
  policies behind the cap.
* [Sign in to the Studio](/studio/login) — the API-key and claim-link sign-in legs.
* [CLI reference](/reference/cli/auth) — `tai auth whoami`, `tai auth claim`, and
  [`tai keys claim-link`](/reference/cli/keys).


# Expose a private tool set
Source: https://docs.tai42.ai/guides/private-tool-set

Publish a scoped sub-MCP server.

Expose a private, scoped set of tools as a sub-MCP server.

A sub-MCP app publishes a named subset of a server's tools under its own slug — a second MCP endpoint carrying only the tools you list. Point a client at the slug and it sees just that set, not the whole server. Use it to scope a client to a private tool set.
[Private tool sets](/concepts/private-tool-sets) explains the model this builds on.

## Register a sub-MCP app

Name the slug to mount under and the tools to expose with the repeatable `--tool`.

```bash theme={null}
tai sub-mcp register utilities --tool convert --tool lookup
```

The app mounts under its slug and re-presents only the named tools. Registering the same slug again reloads it with the new tool set.

## Inspect and remove

**1. List the registered apps**

List the sub-MCP apps and the tools each exposes.

```bash theme={null}
tai sub-mcp list
```

**2. Point a client at the slug**

An MCP client connects to the sub-MCP endpoint the same way it connects to the main server, at the slug's own mount: `/app/{slug}` — so the `utilities` app above answers at `https://<your-server>/app/utilities`. A `tai sub-mcp register` app is served over the streamable **HTTP** transport (the default), the same transport the main MCP endpoint uses. See [MCP clients](/integrations/mcp-clients).

**3. Unregister an app**

```bash theme={null}
tai sub-mcp delete utilities
```

> [!NOTE]
>
> A sub-MCP app is a projection, not a copy. It exposes the same live tools under a narrower surface — a tool removed from the main server disappears from every sub-MCP app that listed it.

## See also

* [Private tool sets](/concepts/private-tool-sets) — the sub-MCP model.
* [MCP clients](/integrations/mcp-clients) — connect a client to the slug.
* [Access control](/concepts/access-control) — gate the sub-MCP endpoint behind a scope.
* [CLI reference](/reference/cli) — the full `tai sub-mcp` surface.


# Schedule a tool
Source: https://docs.tai42.ai/guides/schedule-a-tool

Run a tool on a schedule.

Run a tool on a schedule through the backend.

The runtime runs a registered tool periodically. A schedule names the tool, its arguments, and a cadence; a worker backend fires it on time. Scheduled runs execute on the backend, so a backend plugin must be configured for schedules to run.

## Configure a backend

A schedule runs on the worker backend, not in the request path. Register a backend plugin under `backend_module` in the manifest and start its worker runtime:

```yaml manifest.yml theme={null}
backend_module: myapp.backend
```

```bash theme={null}
tai backend --manifest-path manifest.yml
```

A registered backend needs the [worker bus](/concepts/worker-bus) and a shared [hooks registry](/concepts/hooks#managing-hooks-live): set `TAI_BUS_REDIS_URL` and `HOOKS_REDIS_URL` (or `TAI_DEFAULT_REDIS_URL` for both), or `tai serve` and `tai backend` refuse to start. See [Backends](/concepts/backends) for where tools run.

## Attach the schedule extension

A schedule on a cadence fires the tool's `<tool>_schedule_task` vehicle — the backend's `schedule_task` [extension](/concepts/tools-and-extensions). You always name the base tool; the server resolves the vehicle. Naming the backend under `backend_module` registers that extension, but it is never attached to a tool on its own: name it in the tool's per-tool `extensions` map so the vehicle exists.

```yaml manifest.yml theme={null}
backend_module: myapp.backend

tools:
  - title: my_tools
    module: myapp.tools
    include: [report]
    extensions:
      report: [schedule_task]
```

Without the extension the tool has no schedule vehicle, and `tai schedules add report --cron ...` answers a `404` — the cadence has nothing to run on. `GET /api/tools/tags` marks each tool `schedulable` when its vehicle is registered, which is how Studio's schedule dialog picks the tools it offers.

## Add a schedule

Name the base tool and its cadence. Pass tool arguments with `--tool-kw key=value` (or `--tool-kwargs` as JSON), and give the cadence with at most one of:

* **`--cron EXPR`** — a crontab expression: 5 fields (`minute hour day-of-month month day-of-week`), or 6 with a leading seconds field, which is dropped.
* **`--every SECONDS`** — an interval, in seconds (greater than 0).
* **`--cadence JSON`** — the cadence object itself (below).

```bash theme={null}
tai schedules add report --cron '0 9 * * *' --schedule-name morning-report
```

With no cadence option the tool runs **once, now**. `--schedule-name` names a recurring schedule (its handle for `tai schedules delete`); it needs a cadence. Without it the server derives a name from the tool, its arguments and the cadence, so re-adding the same schedule updates it in place — pass `--schedule-name` when you want an explicit, stable handle.

### The cadence

Every door speaks one cadence shape, discriminated by `kind`:

```json theme={null}
{"kind": "interval", "every": 60, "relative": false}
{"kind": "crontab", "minute": "0", "hour": "9", "day_of_month": "*", "month_of_year": "*", "day_of_week": "*"}
```

`relative` aligns an interval to its own clock. The Celery backend honours it; the arq and RQ backends cannot, and refuse a schedule with `relative: true` rather than ignoring it.

Over HTTP, `POST /api/schedules` takes the same fields:

```bash theme={null}
curl -X POST .../api/schedules -H 'Content-Type: application/json' -d '{
  "tool_name": "report",
  "tool_kwargs": {"recipients": ["alice"]},
  "cadence": {"kind": "crontab", "minute": "0", "hour": "9"},
  "schedule_name": "morning-report"
}'
```

The body is closed: an unknown key is a `400`, and so is naming the `<tool>_schedule_task` vehicle as `tool_name` or giving `schedule_name` without a `cadence`.

## Driving parked interactions

A schedule can also be a **parkable-driving door**: on each fire it can cancel, resume,
take, or start runs against the [parked interactions](/concepts/asking-the-caller) on
its subject. Pass the four [door-contract](/concepts/asking-the-caller#the-door-contract)
jqs — each evaluated over the schedule's fired tool arguments with the run's parked
interactions bound as [`$parked`](/concepts/jq-variables#doors):

```bash theme={null}
tai schedules add report --cron '0 9 * * *' \
  --execution-key svc \
  --start-expr '{waiting: ($parked | length)}' \
  --resume-expr '$parked[0].id'
```

* **`--start-expr`** builds the fired tool's kwargs (`null` starts nothing).
* **`--cancel-expr`** names parked interaction ids to cancel.
* **`--resume-expr`** names an ask to resume with an answer (`{id, payload}`) or a
  waiting outcome to take (a bare id).
* **`--extras-expr`** builds the `extras` mapping handed to the started target.

Any of the four requires **`--execution-key`** — the identity the fired run runs as. A
schedule fire has no receiver, so a resumed run's terminal
[waits on the subject](/concepts/asking-the-caller#waiting-outcomes) for its next owner
to take.

> [!NOTE]
>
> A schedule created with a `state_binding` has the binding checked and its templates attached
> at create, before the backend stores anything: a binding naming an undeclared state is a `404`,
> an occupied attach path a `409`, and a states-store failure a `500`. See [saving a
> binding](/concepts/states#saving-a-binding).

## Inspect and remove

**1. List schedules**

```bash theme={null}
tai schedules list
```

Each row names the schedule, the tool it fires, its cadence, whether it is enabled, and its next run — never the stored tool arguments.

**2. Check the server clock**

Cron cadences resolve against the server's clock — read it to reason about when a job fires.

```bash theme={null}
tai schedules server-datetime
```

**3. Delete a schedule**

```bash theme={null}
tai schedules delete report
```

A schedule the worker cannot recover — one that keeps failing when the watchdog tries to read or re-arm it — carries an `error` (its message and when it happened) in the listing rather than being retried silently forever, so `tai schedules list` tells you which schedule needs attention.

A scheduled run, like every dispatched job, is bounded by the backend's job budget, `<PREFIX>_TASK_TIMEOUT` (see [Backends](/concepts/backends#the-job-budget)).

> [!NOTE]
>
> A schedule and a webhook binding are the two ways a tool fires without a client call. To fire a tool on an inbound event instead, see [Fire a tool from a webhook](/guides/fire-a-tool-from-a-webhook).

## Manage schedules in the Studio

The Studio's **Scheduling** page lists the deployment's schedules: each row names the schedule, its cadence (`Every 3600s`, or `Cron:` and its five fields), whether it is enabled, and the tool it fires. A schedule carrying an `error` shows an **Error** badge beside its status; the badge's tooltip carries the message, and the time it happened when the backend recorded one. The page also shows the server clock that cron cadences resolve against.

![The schedules table with columns Name, Schedule, Status, Tool and Actions: hourly-sync every 3600 seconds, nightly-refresh and weekly-digest on cron cadences, weekly-digest with an Error badge.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/scheduling-rows-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=44fe78461596472732459e44f2665acf)

The Scheduling page: an interval row, two cron rows, and a schedule with an Error badge.

**Add schedule** opens the create dialog: a name, the tool (only tools the server marks `schedulable` are offered), its kwargs as JSON, and an **Interval** or **Crontab** cadence. Below the cadence sit the schedule's subject, the execution key the fire runs as, and the Start, Cancel, Resume and Extras jqs of [driving parked interactions](#driving-parked-interactions), and the schedule's [state binding](/concepts/states#saving-a-binding).

![The Add schedule dialog with name nightly-refresh, the tool studio\_demo\_echo, an empty kwargs object, Crontab selected with 0 2 \* \* \*, and an execution key chosen.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/schedule-contract-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=8ef02cc3e8f6d978df32cd62c6dcd00e)

The Add schedule dialog on a crontab cadence, with the execution key the fire runs as.

A cron expression of the wrong length is refused in the field, before anything is sent: it takes 5 fields, or 6 with a leading seconds field.

![The Cron expression field holding 0 2 \* \* in its error state, with the message: Use 5 fields (minute hour day-of-month month day-of-week), or 6 with a leading seconds field.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/schedule-cron-error-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=b6365136f885b3b8df438d7258bc9778)

A four-field cron expression refused in the dialog.

## See also

* [Backends](/concepts/backends) — background, scheduled, and distributed execution.
* [Triggers and webhooks](/concepts/triggers-and-webhooks) — the other way a tool fires on its own.
* [CLI reference](/reference/cli) — the full `tai schedules` surface.


# The standard toolbox
Source: https://docs.tai42.ai/guides/standard-toolbox

Enable the shipped default tools and extensions.

Enable the standard toolbox — the shipped default tools and their wrapper and transformer extensions — from a manifest.

The standard toolbox is a batteries-included default set of generic tools and tool extensions. Nothing loads automatically — you opt in per module by naming it in the manifest, exactly like your own code. The tools are self-contained utilities; the extensions are the live demonstration of the clip-on-powers model — memoize, batch, proxy, chain, and meter any tool.

## When to reach for it

* A **tool** from the toolbox gives you a ready-made capability — the current time as a structured object, a random UUID, an HTTP request, embedding vectors.
* An **extension** from the toolbox clips a power onto an existing tool without changing it — `cache` memoizes results, `batch` fans one tool over many inputs, `chain` pipes one tool's output into another, `output_schema` forces a tool's output to a JSON Schema, `proxy` routes its connections through a forward proxy, `prometheus_metrics` meters it.

## Enable the modules

Load a tool module under `tools[].module` and an extension module under `extensions_modules`. Import paths are the module names; the base install stays light, and each heavier module is gated behind an optional dependency that fails loudly at import if missing.

```yaml manifest.yml theme={null}
tools:
  - title: time
    module: tai42_toolbox.tools.current_time_info
  - title: ids
    module: tai42_toolbox.tools.generate_uuid

extensions_modules:
  - tai42_toolbox.extensions.cache
  - tai42_toolbox.extensions.batch
```

With an extension loaded, attach it to a tool through that tool's `extensions` map or `tai tools apply` — see [Apply an extension](/guides/apply-an-extension).

## Run a tool with `--kw`

Run any registered tool synchronously with `tai tools run <name>`. Pass its arguments as repeatable `--kw key=value` pairs — each value is parsed as JSON, falling back to the literal string — or as one JSON object with `--kwargs`:

```bash examples/toolbox/run_tool_kw.sh theme={null}
# Run a registered tool, passing its arguments as repeatable --kw key=value pairs
# (each value parsed as JSON, falling back to the literal string) or as one JSON
# object with --kwargs.
tai tools run --help
```

The tools that take no arguments run bare:

```bash theme={null}
tai tools run current_time_info
tai tools run generate_uuid
```

The rest take their arguments by name — inspect any tool's exact input schema with `tai tools schema <name>`:

```bash theme={null}
# Pad an embedding vector out to a fixed width
tai tools run pad_embeddings --kw embeddings='[0.12, 0.34]' --kw target_dim=8

# Embed a string (or a JSON list of strings)
tai tools run generate_embeddings --kw texts='"the quick brown fox"'

# Make an HTTP request through the curl-backed session
tai tools run request --kw url=https://api.example.com/status --kw method=GET
```

> [!NOTE]
>
> The `request` tool fetches URLs server-side, so it passes tai's URL guard —
> private, loopback, and link-local addresses are refused by default. On a
> self-hosted deployment, reaching a service on the Compose network is an explicit
> opt-in: see [Reaching a service on the Compose network](/self-hosted#reaching-a-service-on-the-compose-network).

## Judge state with `classify`

The `classify` tool judges JSON state against typed questions and returns typed
answers with probabilities — the [classifier](/concepts/classifiers) model type as a
tool. It needs the `classifier` extra (`pip install 'tai42-toolbox[classifier]'`) and
a classifier provider configured through `LLM_PROVIDER_CLASSIFIER` and the
`CLASSIFIER_*` variables.

Call it with a `state` to judge and a named map of `questions`, one of each kind — a
`noul` (yes/no), a `choice` (pick one), and a `score` (rate over a rubric):

```bash theme={null}
tai tools run classify --kwargs '{
  "state": {"subject": "quota exceeded", "retries": 5},
  "questions": {
    "urgent": {"type": "noul", "instructions": "Is this event urgent?"},
    "status": {"type": "choice", "instructions": "Which account status fits?",
               "criteria": {"active": "in normal use", "dormant": "idle", "closed": "ended"}},
    "severity": {"type": "score", "instructions": "Rate the severity.",
                 "criteria": ["low", "medium", "high", "critical"]}
  }
}'
```

The result carries one answer per question, keyed by the question name, each naming
its kind in a `type` discriminator — the `noul` probability, the `choice` label with
its per-label `probabilities`, and the `score` expected value with its per-level
distribution — alongside the `model`, `usage`, and `request_id`:

```json theme={null}
{
  "model": "jev-latest",
  "answers": {
    "urgent": {"type": "noul", "noul": 0.82},
    "status": {"type": "choice", "choice": "active",
               "probabilities": {"active": 0.7, "dormant": 0.2, "closed": 0.1}, "confidence": 0.7},
    "severity": {"type": "score", "score": 2.4,
                 "legend": {"0": "low", "1": "medium", "2": "high", "3": "critical"},
                 "probabilities": {"0": 0.05, "1": 0.15, "2": 0.4, "3": 0.4}, "confidence": 0.6}
  },
  "usage": {"input_tokens": 120, "output_tokens": 30},
  "request_id": "…"
}
```

Every answer stays inside what its question declares: one answer per question, of its
kind, a `choice` label from its `criteria`, and a `score` within its levels. A response
outside them fails the call (see [Answers stay inside what the request declares](/concepts/classifiers#answers-stay-inside-what-the-request-declares)).

Pass `classifier_provider` and `classifier_kwargs` to override the configured provider
and its options for one call. See the [classifiers concept](/concepts/classifiers) for
the question kinds and answer shapes in full.

## The standard set

The tools and extensions the toolbox ships. This table is generated from the plugin registry, so it never drifts from the package.

| Name | Kind | Summary |
| - | - | - |
| `classify` | Tool | Judge JSON state against typed questions and return typed answers. |
| `current_time_info` | Tool | Return the current time as a structured object. |
| `generate_embeddings` | Tool | Generate embeddings for a single string or a list of strings. |
| `generate_uuid` | Tool | Generate a random UUID (version 4). |
| `pad_embeddings` | Tool | Pad each embedding vector with zeros up to a target dimension. |
| `request` | Tool | Execute an HTTP request through a curl-backed session. |
| `batch` | Extension | Branch a tool into a variant that runs many instances at once. |
| `cache` | Extension | Branch a tool into a variant that memoizes results by call arguments. |
| `chain` | Extension | Branch a tool into a variant that transforms its output and calls a next tool. |
| `output_schema` | Extension | Branch a tool into a variant that forces a configured JSON Schema as its output schema and validates every result against it. |
| `prometheus_metrics` | Extension | Branch a tool into a variant that records a Prometheus call metric. |
| `proxy` | Extension | Branch a tool into a variant that runs the wrapped tool through a proxy. |

## Confirm what loaded

```bash theme={null}
tai tools list
tai extensions list
```

> [!NOTE]
>
> The full, always-current list of toolbox tools and extensions — names, kinds, and each item's description — lives on the [toolbox plugin page](/plugins/tai42/toolbox). Per-tool specifics (formats, session behavior, the extras to install) live in the toolbox package's own documentation, linked from that page.

## See also

* [Tools and extensions](/concepts/tools-and-extensions) — the model the toolbox demonstrates.
* [Apply an extension](/guides/apply-an-extension) — attach a toolbox extension to a tool.
* [Toolbox plugin](/plugins/tai42/toolbox) — the full toolbox and its repository.
* [CLI reference](/reference/cli) — inspect what loaded.


# Telegram / Slack to an agent
Source: https://docs.tai42.ai/guides/telegram-slack-to-agent

Bridge a Telegram bot or a Slack app to an agent.

Bridge a Telegram bot or a Slack app to an agent: a message to the bot runs an
agent turn and the answer comes back in the same chat. The bridge is identical to
the [WhatsApp guide](/guides/whatsapp-to-agent) — only the channel plugin, its env
group, and the webhook wiring differ.

Every route still runs its turn **as** a least-privilege `execution_key` — mint and
bind one exactly as in [WhatsApp to an agent](/guides/whatsapp-to-agent#prerequisite-mint-and-bind-a-least-privilege-execution-key)
before creating the route.

## Pick a channel and wire it

The channel package and its env group, the webhook wiring, and the `our_identity`
format live on the plugin page:

> **[channel-telegram](/plugins/tai42/channel-telegram)**
>
> `CHANNEL_TELEGRAM_*`, the **automatic** `setWebhook` registration, and the bot's
> numeric id as `our_identity`.

> **[channel-slack](/plugins/tai42/channel-slack)**
>
> `CHANNEL_SLACK_*`, the Events-API Request URL to set by hand, and the required
> `CHANNEL_SLACK_BOT_USER_ID` as `our_identity`.

Once the channel is configured, create the route binding the bot to the agent:

```bash theme={null}
tai conversations create <route-name> \
  --door channel --target-name chat --execution-key chat-bot \
  --channel <telegram|slack> --identity <our_identity>
```

## Test it and add more

Message the bot and watch the agent reply in the same chat. Read a record with
`tai conversations get-message <route> <message_id>`; list failed deliveries with
`tai conversations failed`. To hand a thread to a human — or let the agent do so — see
[control mode and operator
messages](/concepts/client-conversations#control-mode-and-operator-messages).

More bots or workspaces are more rows — one route per `(channel, our_identity)`
pair.

## See also

* [Client conversations](/concepts/client-conversations) — the model.
* [WhatsApp to an agent](/guides/whatsapp-to-agent) — the execution-key prerequisite
  in full.
* [Conversation bridge reference](/reference/conversation-bridge) — every setting
  and the authorization model.


# Use interactions
Source: https://docs.tai42.ai/guides/use-interactions

Ask a human mid-run with ask, and drive external approvals with ask_external.

Pause a run to ask a person a question and block until they answer.
[Interactions](/concepts/interactions) explains the model this configures.

An interaction suspends the caller mid-run, records the question, and wakes the
caller with the answer. The `ask` tool is the core capability; `ask_external`
extends it to human actions that happen on an outside surface. This guide enables
the feature, asks in each answer format, answers from the CLI, and wires an
external callback end to end. For the model behind it, see
[Interactions](/concepts/interactions).

## Enable interactions

Load the `ask` tool module and the interactions HTTP router — the SSE inbox
stream plus the human answer door.

```yaml examples/interactions/enable_interactions.yaml theme={null}
# Turn on interactions: load the interactions tool module (the LLM-facing `ask`
# question tool and the parked-run tools). The interactions HTTP router (the SSE
# inbox stream + the human answer door) is part of the default router set, so it
# is already mounted.
tools:
  - title: interactions
    module: tai42_skeleton.tools.builtin.interactions
```

An agent or tool that has `ask` in scope can now pause and ask.

## Ask a question

`ask(question, answer_format=...)` is called from inside a tool or agent run.
It records the question, blocks the caller, and returns an `AskAnswer` once a
person responds (or raises on timeout): `answer` is the typed answer below, beside
`reply_to` and `params` (see [Block or park](#block-or-park-sync-and-async)). One question declares one **answer
format**:

| `answer_format` | The human provides | Answer type | Extra fields |
| - | - | - | - |
| `text` | free text | `str` | — |
| `confirm` | a yes/no acknowledgement | `bool` | — |
| `select` | one of a fixed list | `str` | `options` (required) |
| `form` | a typed object | `dict` | `schema` (required) |
| `external` | an action on an outside surface | callback payload | `link` (required) |

The first four are answered on the authenticated **in-client** surface. Example
`ask` calls (the tool input a caller passes):

```json theme={null}
{"question": "What should the release title be?", "answer_format": "text"}
{"question": "Ship the 2.0 release now?", "answer_format": "confirm"}
{"question": "Pick a target environment", "answer_format": "select", "options": ["staging", "production"]}
{"question": "Enter a contact", "answer_format": "form", "schema": {"type": "object", "properties": {"name": {"type": "string"}, "email": {"type": "string"}}, "required": ["name"]}}
```

A form field may declare a shape, such as `"format": "email"`, and the sender may set its own
sentence for a value that breaks it:

```json theme={null}
{"question": "Where should we send the summary?", "answer_format": "form", "schema": {"type": "object", "required": ["email"], "properties": {"email": {"type": "string", "format": "email", "title": "Email address"}}}, "wording": {"form": {"fields": {"email": {"invalid": "Enter your full address", "required": "Enter an address first"}}}}}
```

On WhatsApp and the callback page the person sees *Enter your full address* under the field,
inside the form, before the submit leaves it. Without `wording`, the callback page shows the
platform's *Enter a valid email address*. Each surface's checks and words are set out in
[Shapes are caught inside the form](/concepts/interactions#shapes-are-caught-inside-the-form).

A field left empty reads *Enter an address first* instead: `required` is the sentence for a
missing value, `invalid` for a broken shape.

An optional `group_id` threads related questions, and `timeout` (seconds)
overrides the configured default before the call raises.

## Block or park: sync and async

By default `ask` runs `mode="sync"`: it blocks the caller until a person answers or the
`timeout` elapses, then returns `{answer, reply_to, params}` (`AskAnswer`), with `answer`
the typed answer (as above). The builtin `ask` tool's result is that same object.

The answer comes back unchanged, with two fields beside it. **`reply_to`** is the message
the answering reply quoted, `{message_id, status, text}` — the same shape a conversation
turn reads ([replies to an earlier
message](/reference/conversation-bridge#replies-to-an-earlier-message)) — kept apart from
the answer and never merged into its text; it is `null` when the reply quoted nothing or did
not come over a channel. **`params`** are the channel's own string entries about the
answering tap or reply (for example the `media_*` entries of a photo reply), passed
through with no platform meaning; `null` when there are none, and on expiry. Each channel's
[plugin page](/plugins) names its entries.

On Telegram, a person answers the question "Run the nightly export now?" by replying to it
with a photo captioned "yes". A synchronous `ask` returns:

```json theme={null}
{
  "answer": "yes",
  "reply_to": {"message_id": "4711", "status": "found", "text": "Run the nightly export now?"},
  "params": {"media_kind": "image", "media_id": "…", "media_mime_type": "image/png"}
}
```

(`params` holds the photo's other `media_*` entries too; a tool that parked on the same
question is resumed with the same three values.)

`mode="async"` instead **parks** the caller. The call records the question — and,
with a `channel`, delivers it — exactly as sync does, but returns a **suspension
sentinel** at once rather than blocking. A later answer, or the question's expiry,
resumes the run out of band; the parked question is answered through the same
authenticated answer door or channel callback as any other, never inline.

An async park always carries a deadline. Pass `expiry_at` — a timezone-aware
moment:

```json theme={null}
{"question": "Approve the deploy?", "answer_format": "confirm", "mode": "async", "expiry_at": "2026-06-01T12:00:00Z"}
```

* `expiry_at` is **required** for `async` — an ask with `mode="async"` and no
  `expiry_at` raises.
* `expiry_at` and `timeout` are **mutually exclusive** — they bound the same wait
  two ways, and passing both raises. `expiry_at` is valid only with `mode="async"`.

When the answer arrives, the run resumes on its own: a stored continuation runs under
the **asker's** identity, exactly once. The continuation receives `answer`, `reply_to`
and `params`, the same values a synchronous asker reads; a run parked on the builtin `ask`
tool gets the same `{answer, reply_to, params}` object as the tool's result. What a lapsed `expiry_at` does is the ask's
**`on_expiry`** policy: `on_expiry="kill"` (the default) tears the whole run chain
down, while `on_expiry="resume"` resumes the continuation with a reserved *interaction
expired* marker in place of an answer, so the run takes its expiry branch — set it when
the run has an expiry path to run. The expiry marker arrives as `answer`, with `reply_to`
and `params` `null`.

```json theme={null}
{"question": "Approve the deploy?", "answer_format": "confirm", "mode": "async", "expiry_at": "2026-06-01T12:00:00Z", "on_expiry": "resume"}
```

Async requires the ask to be raised from a resumable run — a resuming driver and an
execution identity bound in scope; raised without one it fails loudly rather than
silently blocking.

An async park also requires the run to sit on a **durable, cross-worker
checkpointer** — `redis` or `postgres`. The parked run's continuation may resume on
a different worker than the one that parked it, so its checkpoint must live in
shared storage; an in-memory, sqlite, or checkpointing-disabled configuration
cannot survive that hop, and a park attempted on one raises loudly rather than
leaving a run nothing could resume.

### Park several at once

A run can raise more than one async `ask` before it suspends — a parallel
fan-out. Each ask is independent: it carries its own `expiry_at`, and its answer or
expiry can arrive in any order, from any surface, on any worker. The run stays parked
until the **last** of them resolves, then resumes once with every answer in hand. An
`on_expiry="resume"` ask that expires contributes the reserved *interaction expired*
marker to its own branch and its siblings' answers ride the same resume; an
`on_expiry="kill"` ask that lapses instead tears the whole fan-out down. Nothing
resumes the run part-way — a partial set of answers buys no progress.

### Agents park too

Async parking is not flow-only. An agent whose tool raises `mode="async"` parks the
whole agent run and resumes it on the answer or expiry, exactly as a flow does. It
needs the same durable, cross-worker checkpointer (`redis` or `postgres`) — an agent
run on an in-memory or sqlite checkpointer refuses the async ask loudly instead of
parking a run nothing could resume.

An agent park also needs the agents package's own durable **park index** — a Redis
that reverses a parked interaction id back to the run that parked it, independent of
the checkpoint provider. Configure it with `TAI_AGENTS_REDIS_URL` (or fall back to
the shared `TAI_DEFAULT_REDIS_URL`), and install the package's `park` extra
(`pip install 'tai42-agents[park]'`). With no park index configured, a park-capable
run refuses the async ask loudly before any state is written.

Parallel subagents each park in one step: when several nested subagents raise an
async ask together, their parks collapse into one suspend and the run resumes once
when the last resolves, every answer in hand — answers and expiries in any order.

When the agent was reached over a chat channel, its resumed final reply is posted
back into the originating thread, so a person who asked hours ago sees the answer
land in the same conversation. A parked **tool or flow** turn reached over that
channel delivers its resumed reply back the same way — mapped through the route's
reply mapping — so a conversation target of any kind lands its late answer in the
originating thread.

### Ask the caller instead of a person

Pass `to="caller"` to address the ask to the **run that called this one** rather than
a person: it parks the asking run and hands the question up, and the calling run
answers by resuming it — no inbox, no channel, no callback. A caller ask is always
`mode="async"`, may carry a structured `payload` the resolving run reads in place of
the `question`, and follows the same `on_expiry` policy. See [asking the
caller](/concepts/asking-the-caller) for the door contract that resolves it.

### The deadline and the retention window

`expiry_at` is the ask's own deadline. It is independent of the **checkpoint
retention** — the horizon the paused run's checkpointer keeps a thread before
reclaiming it: `LLM_PROVIDER_CHECKPOINT_RETENTION_WAITING_MINUTES` after the thread's
last write (7 days by default) on both durable providers, `redis` and `postgres`
(see [Checkpoints and retention](/operate/checkpoints)).
Choose an `expiry_at` inside that window: a park
whose deadline lies beyond the retention horizon could lose its checkpoint
before the answer or expiry arrives, and the run refuses it loudly when it suspends
rather than parking a run its own storage would later strand. An agent run asks for one
more margin: the platform may still deliver an answer or expiry up to
`INTERACTIONS_IDLE_TTL_SECONDS` (1 day by default) after the deadline, so an agent's
deadline must leave that much of the retention free (with the defaults, within 6 days). An ask with no
`expiry_at` at all is rejected too — a deadline that cannot be proven durable is
never parked.

See [Interactions](/concepts/interactions#sync-and-async) for the model.

### An elicitation answered through `ask`

A tool's `ctx.elicit(...)` run in process — with no MCP client to answer it — is answered
through `ask`. Its accepted result carries a `_meta` key `tai42/reply_to`
(`ELICIT_META_REPLY_TO` in the contract), the slot where the quoted message would sit.
Because such an elicitation is answered in the inbox and not on a channel, the key is
`null` there. The answer's `params` are not carried. An elicitation answered by a real MCP
client carries no such key.

## Show images and links with a question

Any question can carry **media** — images and links shown above the answer
controls in the inbox — by passing `media=[...]` to `ask`. Media is
display-only: the person still answers through the `answer_format`. The canonical
use is a `select` that shows each choice:

```python theme={null}
answer = await ask(
    "Which report format do you want?",
    answer_format="select",
    options=["csv", "summary"],
    media=[
        {"kind": "image", "url": "data:image/png;base64,iVBORw0KGgo…", "caption": "The weekly chart"},
        {"kind": "link", "url": "https://docs.example.com/reports", "caption": "Open the full report"},
    ],
)
```

Each item is a `{kind, url, caption?}` object — an `image` (an absolute `https`
URL or a `data:image/*` URI), a `document`, `video` or `audio` file, or a `link` (an
absolute `http(s)` URL) — validated against the contract before the question is
stored:

```yaml examples/interactions/ask_with_media.yaml theme={null}
# Display-only media attached to a question: the images and links a person sees
# above the answer controls in the inbox. Each item is a MediaItem — a kind, a
# url, and an optional caption — and is validated against the contract before the
# question is stored. An image url is an absolute https URL or a data:image/* URI
# (remote images are https-only); a link url is an absolute http(s) URL. Here the
# image is submitted inline as a data:image/png URI and stored by reference — the
# record keeps a /api/interactions/media/<id> url and the bytes are served from
# that route, so nothing is fetched from a remote host.
media:
  - kind: image
    url: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg=="
    caption: "The weekly chart"
  - kind: link
    url: "https://docs.example.com/reports"
    caption: "Open the full report"
```

An agent asks with the builtin `ask` tool using the same shape; `media` is an
array of the same objects:

```json theme={null}
{
  "question": "Which report format do you want?",
  "answer_format": "select",
  "options": ["csv", "summary"],
  "media": [
    {"kind": "image", "url": "data:image/png;base64,iVBORw0KGgo…", "caption": "The weekly chart"},
    {"kind": "link", "url": "https://docs.example.com/reports", "caption": "Open the full report"}
  ]
}
```

![The Studio Interactions inbox rendering a question together with its attached images and links.](https://mintcdn.com/tai42/svAMgtenosCg9O5X/images/studio/scoped-interactions-light.png?fit=max\&auto=format\&n=svAMgtenosCg9O5X\&q=85\&s=e0f5efe77c5571dbff006a97e850c483)

A question with its media rendered in the Studio inbox, above the answer controls.

Media renders in the Studio inbox only — it is **not forwarded to a channel**
delivery, which carries the question text. See
[Media on a question](/concepts/interactions#media-on-a-question) for the accepted
url forms, the caps, and the privacy note.

## Answer from the CLI

A pending question surfaces on the paged list and the tail-only SSE stream — the
Studio inbox, or the CLI. Print one page of the pending list, tail the stream live,
or answer one:

```bash theme={null}
tai interactions list --page 1 --page-size 50   # print one page of the pending list, then exit
tai interactions stream                          # tail the live add/answered/removed stream
```

The answer value is **JSON**, matching the question's format — a string for `text`
and `select`, a bool for `confirm`, an object for `form`:

```bash examples/interactions/interactions_answer_help.sh theme={null}
# Answer a pending in-client question. The value is JSON: a string for text and
# select, a bool for confirm, an object for form.
tai interactions answer --help
```

```bash theme={null}
tai interactions answer i_123 --answer '"Point release 2.0.1"'   # text
tai interactions answer i_123 --answer 'true'                    # confirm
tai interactions answer i_123 --answer '"production"'            # select
tai interactions answer i_123 --answer '{"name":"Ada","email":"ada@example.com"}'  # form
```

The value is validated server-side against the question's declared format and
schema; a mismatch is rejected with a 400 that names the failing field (for
example, `answer does not match schema at count: ...`), and the caller stays
blocked.

## External questions and the callback flow

The `external` format is for actions a person completes on an outside surface —
signing a document, approving a request, paying. The asking tool blocks exactly as
for any other format; only the delivery channel differs. The external system
delivers the answer back through a **public callback door**, not the answer door.

The `ask_external` transformer extension packages the whole flow. It wraps a tool
that builds an external resource from a `callback_url` and returns the URL to
visit. Attach it in the manifest, binding an optional webhook verifier that
authenticates the signed callback:

```yaml examples/interactions/attach_ask_external.yaml theme={null}
# ask_external is a transformer extension. Load its module, then attach it to a
# tool that builds an external resource from a callback_url. The verifier is
# author-bound extension config that authenticates the signed callback — it is
# never an LLM-facing tool parameter, so a calling agent cannot drop or forge it.
extensions_modules:
  - tai42_skeleton.extensions.builtin.ask_external
webhook_verifier_modules:
  - tai42_webhook_verifier_github
tools:
  - title: signing
    module: myapp.signing
    include: [make_signing_envelope]
    extensions:
      make_signing_envelope:
        - - name: ask_external
            config:
              verifier:
                verifier: github
```

The `verifier` is **author-bound extension config** — it is closed over at build
time and is never an LLM-facing parameter, so a calling agent can neither drop nor
forge the callback authentication. The wrapped tool keeps its own inputs; the
extension injects `question` / `answer_schema` / `timeout` and hides
`callback_url` (the platform supplies it).

At run time, calling the composed tool:

1. builds the external resource, substituting the minted `{callback_url}` into the
   `link` (or handing it to a callable link that returns the final URL);
2. blocks the caller while the person acts on that surface;
3. accepts the answer when the external system POSTs the signed payload to
   `POST /api/interactions/callback/{ticket}` (verified first when a verifier is
   bound), or when a person completes the GET confirm page;
4. validates the payload against the question's `schema` when one is declared, and
   returns it to the blocked caller.

> [!NOTE]
>
> External questions (and any `channel`-delivered question) require
> `INTERACTIONS_PUBLIC_BASE_URL` — an `https://` origin, since the callback URL is a
> bearer capability — and Redis. Callback payloads arrive through an
> unauthenticated door, so treat every delivered answer as untrusted input.

## Confirm through an external system

A confirmation ask is an `external` question whose outside surface is a resource the
external party acts on. The composed `request_confirmation_ask_external` tool opens
the ask, the party confirms on that surface, the external system signs a
confirmation webhook, and a bridge hook answers the blocked caller. Two per-question
locks make that flow safe to hand an LLM, and a preset makes the confirmation
un-forgeable by the agent. Everything below is what an operator deploys, in order.

### The two per-question locks

An ask that merely "waits for a confirmation" is not request-bound. Two locks bind
it, both declared per question:

* **The verifier binding** authenticates the signed callback. Under the composed
  tool it is author-bound extension config (`verifier`), closed over at build time
  and never a call argument, so a calling agent can neither drop nor forge the
  callback authentication.
* **The const-pinned answer `schema` IS the request binding.** The callback door
  validates the delivered payload against it *before* it claims the ticket, and a
  mismatch returns 400 without consuming the ticket. Pin `reference` and `decision`
  to consts so a webhook can only confirm the request the ask names:

  ```json theme={null}
  {
    "type": "object",
    "required": ["reference", "decision"],
    "properties": {"reference": {"const": "A-42"},
                   "decision": {"const": "confirmed"}}
  }
  ```

  Under the composed tool this is the `answer_schema` argument; under a direct
  `ask` call it is `schema=`. **An ask without it is not request-bound** — any
  signed webhook the door accepts would claim the ticket, whatever request it
  confirmed.

### The pinning preset is required, not optional

Every request-facing parameter — `reference`, `return_url` AND `answer_schema` — is
an agent-suppliable argument on the composed `request_confirmation_ask_external`
tool. An agent that reads an injected instruction can therefore point the ask at a
different `reference`, redirect the external party to an attacker page, or drop the
pin entirely (`answer_schema` defaults to `None`, leaving the ask claiming whatever
the bridge posts).

The fix is a preset that bakes all three as hidden fixed constants — removed from
the exposed schema, and rejected outright if a caller passes one. `answer_schema`'s
`reference` const is written from the SAME literal as `reference`, so the request
and the pin cannot disagree. **Give agents the preset and never the raw composed
tool.**

```json theme={null}
{
  "name": "confirm_a42",
  "base_tool": "request_confirmation_ask_external",
  "description": "Ask the external party to confirm request A-42.",
  "fixed_kwargs": {
    "reference": "A-42",
    "return_url": "https://acme.example/done",
    "answer_schema": {
      "type": "object",
      "required": ["reference", "decision"],
      "properties": {"reference": {"const": "A-42"},
                     "decision": {"const": "confirmed"}}
    }
  }
}
```

Note what is NOT there: an `extensions` key. An explicit `"extensions": []` is
rejected with a 400 (omit the field for no extensions). `decision` is pinned to
`"confirmed"` so a declined or partial answer cannot claim the ticket as a
confirmation.

> [!WARNING]
>
> **This preset JSON is the reviewed artifact.** The platform never validates a
> schema's *shape*, so a human reading this body is where the pin's correctness
> actually lives — and it holds only for as long as nobody rewrites the stored body
> through `POST /api/presets/{name}/versions`, which is a plain `write` door that
> replaces `fixed_kwargs` wholesale. On a deployment that acts on confirmations,
> `write` can rewrite the binding itself.

### Manifest wiring

Three pieces compose the flow: the `stripe` verifier under the canonical
`webhook_verifier_modules` field for the `webhook-verifier` kind; the built-in
`shared_secret` verifier under `lifecycle_modules` (it authenticates the *bridge*
at the callback door, and loads only through the manifest — without it the
per-question binding fails closed); and `ask_external` under `extensions_modules`,
ATTACHED to `request_confirmation` through the `extensions` map. The attachment map
is the piece that actually composes the agent-facing tool — loading the extension
module without it gives the bare builder and no composed tool at all.

```yaml examples/interactions/confirm_through_external.yaml theme={null}
# Wire an external-confirmation ask end to end. Three pieces compose it:
#   * the stripe webhook verifier, under the canonical webhook_verifier_modules
#     field for the webhook-verifier kind — it authenticates the signed delivery
#     at the topic ingress;
#   * the built-in shared_secret verifier, loaded via lifecycle_modules — it
#     authenticates the BRIDGE at the interaction callback door (the X-TAI-Bridge-Secret
#     header), and it loads only through the manifest;
#   * ask_external, loaded via extensions_modules and ATTACHED to
#     request_confirmation through the extensions map below — the attachment is
#     what composes the agent-facing request_confirmation_ask_external tool.
# Loading the extension module WITHOUT the attachment map gives the bare builder
# and no composed tool at all. Give agents the pinned preset baked over the
# composed tool, never the composed tool itself.
webhook_verifier_modules:
  - tai42_webhook_verifier_stripe
lifecycle_modules:
  - tai42_skeleton.webhooks.builtin.shared_secret
extensions_modules:
  - tai42_skeleton.extensions.builtin.ask_external
tools:
  - title: request-confirmation
    module: example_tools.confirmation.request_confirmation
    # The verifier here is author-bound extension config — it authenticates the
    # bridge's callback POST, and is never an LLM-facing tool parameter.
    extensions:
      request_confirmation:
        - - name: ask_external
            config:
              verifier:
                verifier: shared_secret
                config:
                  header: X-TAI-Bridge-Secret
                  secret_env: TAI_BRIDGE_CALLBACK_SECRET
  - title: confirm-action
    module: example_tools.confirmation.confirm_action
  - title: reconcile-confirmations
    module: example_tools.confirmation.reconcile_confirmations
```

The `stripe` verifier ships in `tai42-webhook-verifier-stripe` (present on the
distribution image; elsewhere install it with `pip install
tai42-webhook-verifier-stripe`). The `request_confirmation`, `confirm_action` and
`reconcile_confirmations` tools are the deployment's own.

### Operator prerequisites

Beyond the manifest, the deployment needs:

* **The external system's API credential** — read by the reconcile tool to list
  recent confirmations from the external system.
* **A webhook endpoint configured on the external system**, its API version pinned
  explicitly where the provider versions its payloads, plus its signing secret in
  the env var the topic binding names (`secret_env`).
* **`INTERACTIONS_PUBLIC_BASE_URL`** — an `https://` origin. It is both the
  reachability requirement for the minted callback URL and the ground truth the
  bridge's SSRF pin compares against.
* **`TAI_BRIDGE_CALLBACK_SECRET`** — one value read by BOTH the door's
  `shared_secret` verifier and the bridge tool. It must be present on **every**
  process that answers (app and worker), rotated in a **coordinated** change
  across them, and note the **read asymmetry**: the door reads it to authenticate
  the bridge, the bridge reads it to sign. Missing on the door, the verifier
  raises and the door 500s; the bridge then sees a retryable 5xx and burns its
  whole retry ladder against it — an operator fix (set the secret), not a code
  one.
* **A configured versioned-document store.** Without it no preset can be created
  at all — the binding itself cannot exist.
* **A PUBLIC route row** for `/universal_webhook/*` on an access-control-enabled
  deployment. That door is unauthenticated by nature (the external system carries
  no API key) and is a non-`/api` path the gate's declared-public tier does not
  reach, so it needs the row. An unconfigured route 403s, and a 403 is on the
  bridge's fail-fast list — i.e. confirmed-but-unanswered. The
  `/api/interactions/callback/*` door needs no row: it registers `authed=False`, so
  the gate publics it straight from its declaration.

### Bind, register, bake — in this order

Order matters: **bind the verifier FIRST.** Between registering the hook and
binding the verifier, the topic is an open unauthenticated door straight into the
bridge — ingress verification runs only when a binding exists. There is a second,
stronger reason: a `/trigger/{token}` link cannot be minted on a verifier-bound
topic at all (the mint is refused 400), so binding first shuts that door before it
can be opened; bind late and any holder of `hooks` write can mint a link on the
still-unbound topic in the gap.

```bash theme={null}
# 1. bind the verifier to the topic (admin-fenced route) — ALWAYS FIRST
curl -X PUT .../api/hooks/topics/confirmations/verifier \
  -d '{"verifier": "stripe", "config": {"secret_env": "WEBHOOK_SIGNING_SECRET"}}'

# 2. register the bridge hook — the start_expr is REQUIRED, the condition is required too
curl -X POST .../api/hooks -d '{
  "name": "confirmations-bridge",
  "topic": "confirmations",
  "tool": "confirm_action",
  "execution_key": "<key user_id>",
  "condition": {"content": ".type == \"confirmation.completed\""},
  "start_expr": {"content": "{event: {type: .type, id: .id, reference: .data.object.reference, decision: .data.object.decision, metadata: .data.object.metadata}}"}
}'

# 3. bake the pinning preset over the composed ask tool — the agent-facing tool.
#    reference and answer_schema.properties.reference.const are the SAME value,
#    written once.
curl -X POST .../api/presets -d '{
  "name": "confirm_a42",
  "base_tool": "request_confirmation_ask_external",
  "description": "Ask the external party to confirm request A-42.",
  "fixed_kwargs": {
    "reference": "A-42",
    "return_url": "https://acme.example/done",
    "answer_schema": {
      "type": "object",
      "required": ["reference", "decision"],
      "properties": {"reference": {"const": "A-42"},
                     "decision": {"const": "confirmed"}}
    }
  }
}'
```

The `start_expr` is not optional: hook dispatch passes the tool NOTHING without one, so
`confirm_action` would be called with no `event` and fail on every delivery. It is
deliberately narrow to keep the payload small — but it necessarily carries
`metadata` (holding `tai_callback_url`, a live answer capability). Treat hook traces
on a confirmations topic as holding a live ticket, and restrict read access
accordingly. The `condition` gates the hook so only `confirmation.completed` events
fire it; without it every event on the topic fires the bridge, which raises loudly
on the wrong type and floods the only failure surface this design has.

The hook fires under its bound `execution_key`'s identity. That key is identity
and liveness only — for a capability tool the authorization layer never runs a
per-tool check — so bind a key the operator owns and control the surface by
restricting who may WRITE hooks. Binding a key is mandatory: a hook with none is
refused before it fires.

### The channel constraint

A confirmation ask can never be channel-forwarded — `verifier` is forbidden together
with `channel`, because a channel's forward is unsigned and would 401 every reply.
Confirmation questions live on the inbox / API surfaces only.

### The reconciliation schedule

The platform keeps every webhook event it accepts: a `200` means the event is kept. A
hook run that fails or meets a restart is retried or held as failed (see [Kept and
retried](/concepts/hooks#kept-and-retried)). A bare hook is still not a delivery
guarantee, because two cases stay beyond the platform: an event that never arrives
(the external system never sent it, or gave up on its delivery), and a hook run held
as failed, which waits for an operator. Deploy the recovery layer as part of deploying
confirmations, never as an optional extra.

`reconcile_confirmations` lists recent confirmations from the external system (a
time-window query plus a server-side narrowing to completed ones), selects the ones
that are `confirmed` AND carry `metadata.tai_callback_url`, and answers each through
the same pinned bridge path. It reads the external system rather than platform
state, so it recovers a webhook that never arrived and a confirmation whose hook run
is held as failed. Re-answering an already-answered ask is free.

Create the schedule through the authed schedules door:

```bash theme={null}
curl -X POST .../api/schedules -d '{
  "tool_name": "reconcile_confirmations",
  "tool_kwargs": {},
  "cadence": {"kind": "interval", "every": 900},
  "schedule_name": "reconcile-confirmations"
}'
```

The `cadence` is the same typed shape on every backend (see [Schedule a
tool](/guides/schedule-a-tool#the-cadence)). **When no scheduling backend is installed the
door 501s** — there is no schedule to create, and reconciliation runs only as a
manual authed tool call, so an event that never arrived is recovered only by that call.

The worker that runs the schedule needs three things the app already has: its own
manifest must load the confirmation tools module (a tool the worker never imported
cannot run by name); its Python environment must carry the confirmation tools and
the external system's client; and its environment must carry the external system's
API credential, `TAI_BRIDGE_CALLBACK_SECRET` and `INTERACTIONS_PUBLIC_BASE_URL`
with the callback door dialable FROM the worker.

**Cadence and lookback are a coupled pair — document them together, never one
alone.** A 15-minute cadence bounds recovery lag to well under any realistic ask
`timeout`, and overlapping runs stay safe because every answer is idempotent. It is
not free: at 15 minutes against a 26-hour lookback each confirmation is re-scanned
and re-POSTed on roughly **104 consecutive runs** — \~104× the door traffic, external
list calls and log volume of a single delivery. Tightening the cadence multiplies
the overlap; shortening the lookback shrinks the recovery window. Answers are serial
and paced (an answer interval, \~1.2s by default) because a run is one worker address
against a door that limits per client address; a deployment that lowers the interval
to clear a bigger window must raise the `interactions_callback` family's budget
([flood control on public doors](/concepts/access-control#flood-control-on-public-doors))
in the same change.

**Runbook — an outage longer than the lookback is not recovered automatically.**
Each run sees only confirmations created inside `lookback_hours` of that run, so
confirmations from a longer outage have aged out of every subsequent window. After
any outage longer than the reconciliation lookback, run `reconcile_confirmations`
once by hand with a `lookback_hours` large enough to cover it.

### The confused deputy, and the rules that close it

The external system's signature is verified at the topic ingress. The interaction
callback door verifies something else entirely — the `X-TAI-Bridge-Secret` header,
i.e. "this POST came from the bridge". `confirm_action` holds that secret and answers
with whatever `event` dict it is invoked with. So the real trust boundary is:
**anything in-process that can call `confirm_action` with a crafted event and a live
ticket can answer a confirmation ask** — and the blast radius is one notch wider
still, because neither tool knows which question a callback URL belongs to. The
capability is "answer ANY live external interaction whose ticket it is handed".
Confirmation asks are the protected case precisely because they bind the verifier
and pin the const schema; an ordinary unbound external ask has nothing that refuses
a forged answer.

There is no lever that keeps a registered tool off "every surface an LLM or API
caller can reach": `POST /api/tool-runs`, `POST /api/schedules`,
`POST /api/agents/{name}/run` and the MCP edge are all run-any-registered-tool
doors at `write`, a capability tool carries no per-call authorization decision, and
the preset version doors are `write` too. The hard requirements, stated to what
actually enforces them:

1. **Restrict `write`** on any deployment carrying a confirmations topic — the
   tool-runs, schedules, agent-runs and preset-version doors, and the MCP edge.
   ANY holder of `write` can `POST /api/tool-runs` with a crafted `event` and forge
   an answer for any ticket they know — no external access, no signing secret, no
   hook — and can rewrite the binding through the preset version door. `write`
   IS the ability to forge a confirmation answer.
2. **Restrict `hooks` write** — a separate, equally hard requirement. Hook register
   is an UPSERT by name and `POST /api/hooks` is plain `write`, so a `hooks`-write
   holder can register a hook on a topic they name themselves — which has no
   verifier bound and so an unauthenticated ingress — set `tool="confirm_action"`,
   bake the forged event into the hook's own `tool_kwargs` (author kwargs merge
   strongest), bind their OWN execution key, and fire it with one anonymous POST.
   The same upsert-by-name also lets them rewrite the real bridge hook's `start_expr` in
   place. Verifier binding fences DELIVERY, never hook authorship; only restricting
   `hooks` write does that.
3. **Exclude four names** from `user_tools` and every agent toolset:
   `confirm_action`, `reconcile_confirmations`, `request_confirmation` AND the
   un-preset composed `request_confirmation_ask_external`. Agents are given the
   pinned PRESET and nothing else. This is caller discipline with no enforcing
   lever — an agent's toolset is what the run request names, not what the manifest
   says — so its backstop is rule 1 on the agent-runs door.
4. **Treat tickets as secret.** The bridge secret is required in addition to the
   ticket, so a stolen ticket alone forges nothing — but a ticket plus a `write`
   grant does. Treat hook traces, tool-run records and logs on a confirmations topic
   as holding live answer capabilities and restrict read access accordingly.
5. **Never unbind the verifier while the topic is live.** The binding is the ONLY
   thing between the registered bridge hook and the open internet; unbinding turns
   that hook into an anonymous forge endpoint instantly. Retiring a confirmations
   topic means deleting the HOOK first.

The const-pinned schema is the control that survives a breach of rules 1–4, and its
limit is worth stating: a forged answer must carry exactly the `reference` and
`decision` the ask declared, or the door 400s it and leaves the ticket unconsumed.
That defeats an attacker who cannot choose the payload. It does NOT defeat an
attacker who writes the payload directly, because the pinned values are not secret
(the reference is visible to the external party and in the callback metadata).

### Failure paths, stated honestly

**The bridge retries transient door failures.** Connection errors, HTTP 5xx, 408
and 429 retry with bounded exponential backoff (5 attempts, \~0.5s base, doubling,
jittered); a `Retry-After` on a 429 is honoured in full up to a 90-second ceiling,
because the callback door's [flood
limiter](/concepts/access-control#flood-control-on-public-doors) is a fixed-window
counter whose `Retry-After` is the seconds left in that window. **400, 401, 403 and
404 fail fast** — a schema mismatch, a wrong secret, a refused caller (an unpinned
access-control route answers exactly this) and an expired ticket are verdicts no
retry changes. Exhaustion raises.

**Read the reconcile run summary as five disjoint outcomes:**
`selected == answered + already_answered + expired + rejected + len(failed)`.

* `answered` is a recovered confirmation; `already_answered` is the healthy norm.
* **`expired`** means the ticket no longer resolves — read it as exactly that,
  nothing narrower: the tool cannot distinguish an ask that DIED from one answered
  long ago whose ticket has since aged out of its `idle_ttl_seconds` (24h default).
* **`rejected`** is the door's 400 and nothing else — the ask's own schema pin
  refusing THIS payload — reported and never raised, so a permanently unanswerable
  confirmation does not fail every run. The remedy: an operator inspects the named
  confirmation; preset drift (a stored `fixed_kwargs` no longer matching the
  confirmation's reference) is the usual cause.
* **`failed`** is everything that is not a verdict on one confirmation — transport
  failures, 5xx exhaustion, and the two refusals that read per-confirmation but are
  really deployment-wide breakage arriving one at a time: a **403** (no PUBLIC route
  row) and an **SSRF-pin refusal** (`INTERACTIONS_PUBLIC_BASE_URL` disagreeing with
  every callback URL). All of `failed` is collected and raised at the END of the
  run.

TTL, lookback and cadence are three coupled numbers. The claimed-ticket TTL
refreshes to `idle_ttl_seconds` (default **24h**) while the reconciler's default
lookback is **26h**, so a healthy answered confirmation reports `already_answered`
for its first 24h in the window and `expired` for at most the last \~2h — a steady
`expired` count on a healthy deployment is that overhang, not a lost confirmation.

> [!WARNING]
>
> **One deployment-wide failure slips into `expired`.** If the callback ROUTE stops
> being served at all — a dropped ingress rule, a proxy pointed at the wrong upstream,
> the door unmounted — the origin still matches `INTERACTIONS_PUBLIC_BASE_URL`, so
> every POST draws a route-level 404, every confirmation lands in `expired`, `failed`
> stays empty, and the run does NOT raise. Nothing in the response distinguishes it
> from an aged-out ticket; what does is the SHAPE of the summary — `expired ==
>   selected` on a run that should have answered something. Alert on that shape, not
> just on `failed`.

**Abandoned and expired confirmations.** A party who never acts blocks the ask until
its own `timeout`, then it raises — there is no other end state. An external
confirmation link expires on the external system's own schedule, which can outlive
or undercut the ask's `timeout`; authors must choose the ask `timeout` with the
link's lifetime in mind. A webhook that lands after the interaction was pruned gets
the door's uniform 404 and the bridge raises loudly on it (a typed error carrying
`.status == 404`) — the confirmation is recorded at the external system and the agent
never learns of it; reconciliation counts it `expired` rather than failing the run.
`return_url` is where the external party lands after acting and has NO platform
effect — it is baked into the preset only because it is a party-facing redirect and
an agent-suppliable one is a prompt-injection target. The bridge accepts ONLY a
`decision` of `confirmed`, rejecting any other value loudly.

**A captured signed delivery is refused on replay inside the tolerance window.** The
stripe verifier claims a seen-set entry keyed on the `event.id`, with a TTL anchored to
the signed timestamp that runs until the freshness window ends (`t + tolerance_seconds`),
so on the webhook ingress a
replayed signed delivery draws the idempotent `already_seen` 200 — nothing dispatched,
no duplicate hook fires. The interactions callback door verifies the signature but does
not consult that seen-set; there a replay is absorbed by ticket state, where an answered
ticket returns the idempotent `already_answered` 200 — so no double answer on either door.

### The callback doors and the ticket-state oracle

For a verifier-bound confirmation question the doors give a caller without the bridge
secret nothing to read: **the GET door answers one constant 404** whether the ticket
is unknown, expired, live or answered, and **the POST door verifies BEFORE it reports
`already_answered`**, so a caller without the secret sees the same 401 either way. A
genuine provider retry still passes verification and gets its idempotent 200. One
residual stays: on the POST door a bound-ticket holder can still tell a resolvable
ticket (401) from a dead one (404), because the binding lives in the interaction
state and cannot be read before that state is — "this ticket existed recently", not
"there is an unanswered confirmation worth attacking".

One behaviour to know: an answered bound question whose verifier cannot RUN — an
unregistered verifier name, a malformed binding, or a verifier raising something
other than a verification failure — answers **500** where an unbound question would
answer the idempotent 200. That is correct (a door that cannot authenticate must not
report state) but a bridge sees a retryable 5xx and burns its whole ladder against
it, so the fix is an operator one: register the verifier module (and, for the
built-in, set the `secret_env` it reads).

### Doctrine and residuals

The signed webhook is the only answer path from OUTSIDE; the author's `return_url`
page is pure UX; the external party never sees the callback URL; and the callback
door authenticates the BRIDGE, not the external system. A confirmation is lost to
the agent only when both the webhook and reconciliation fail inside the ask's own
`timeout` window — most realistically because reconciliation was never scheduled, or
the scheduler was down longer than both the ask and the lookback. Then the party
acted, the ask dies at its `timeout`, and the surface is the hook run held as failed
(`tai hooks runs list --status failed`, the operator notification and the
`hooks_run_failed` event; see [Kept and retried](/concepts/hooks#kept-and-retried)),
or nothing at all when the event never arrived. The recovery layer is only real once
it is installed.

## Deliver to a channel instead

Passing `channel="<name>"` to `ask` hands delivery to a registered
channel plugin — Telegram, Slack, SMS/WhatsApp — instead
of the default inbox: the question mints a public callback ticket exactly like an
`external` ask, the plugin pushes it to the person, and the reply returns through
the same callback door. An optional `recipient` names the per-call address; an
unknown channel name or a delivery failure raises loudly before the run would wait
on an answer that can never arrive.

A `form` ask rides a channel only when that channel advertises
`supports_form_delivery`; a form sent to a channel without the flag raises loudly,
naming the channel, before anything leaves the run. Among the bundled channels:

* **web** renders a schema-driven form widget inline in the chat;
* **Slack** posts a message whose button opens a Block Kit modal;
* **WhatsApp** sends the form as an in-chat WhatsApp Flow;
* **Telegram** offers a button that opens the schema-rendered callback form page as
  an in-chat webview;
* **Twilio** (SMS and WhatsApp-via-Twilio) advertises no form support, so a form ask to it is refused.

The callback form page the GET callback door renders from the question's schema is
the generic surface behind those native renderings.

A channel form's `schema` must fall in the renderable
[channel-deliverable subset](/concepts/interactions#delivering-to-a-channel) —
scalar properties or an array of strings, optionally carrying
[date constraints](/concepts/interactions#date-constraints) and
[`visibleWhen`](/concepts/interactions#conditional-fields) — validated when the
question is asked, before anything is stored; a `ValueError` names the offending
property. A form on the default inbox surface keeps full schema freedom.

## See also

* [Interactions](/concepts/interactions) — the loop, the doors, and the security model.
* [Triggers and webhooks](/concepts/triggers-and-webhooks) — the verifier that authenticates a signed callback.
* [CLI reference](/reference/cli) — the full `tai interactions` surface.


# Use the ready-made agents
Source: https://docs.tai42.ai/guides/use-the-ready-made-agents

Enable and run the seven shipped agents.

Enable and run the ready-made agents that ship with the platform's default set.

The ready-made agents are a batteries-included default set — agents built against the same `Agent` contract as any agent you write, packaged so you can enable them without writing code. You enable them the same way you enable any agent module: name the module in the manifest, then list and run.

## Enable them

Each agent lives in its own module, and **importing a module is what registers its agent** — so name one `agents[]` entry per module. (Naming the top-level `tai42_agents` package alone registers nothing: it imports no submodule.) To drive agents from a UI over an SSE stream, also load the agents router.

```yaml examples/agents/enable_ready_made.yaml theme={null}
# Enable the ready-made agents. Each agent lives in its own module, and importing
# a module is what registers its agent — so name one agents[] entry per module
# (naming the top-level `tai42_agents` package alone registers nothing). The
# agents router that drives runs over SSE is part of the default router set, so it
# is already mounted.
agents:
  - title: tools-agent
    module: tai42_agents.tools_agent
  - title: langchain-deep-agent
    module: tai42_agents.langchain_deep_agent
  - title: retrieval-tools-agent
    module: tai42_agents.retrieval_tools_agent
  - title: voting-agent
    module: tai42_agents.voting_agent
  - title: refine-agent
    module: tai42_agents.refine_agent
  - title: vqa-agent
    module: tai42_agents.vqa_agent
```

Use `include` on an entry to enable a subset of a multi-agent module by name; each module here defines a single agent, so `include` is unnecessary above.

## List and run

**1. See what registered**

List every registered agent, then the spec-runnable (authorable) ones.

```bash theme={null}
tai agents list
tai agents spec-runnable
```

**2. Run one**

Every agent runs the same way — stream a run one event frame at a time, passing the agent's input as a JSON object. The input fields are the agent's own `ToolInput`; read a schema with `tai tools schema <agent-run-tool>`.

```bash examples/agents/agents_run_help.sh theme={null}
# Every agent runs the same way: tai agents run <name> --input '<JSON>'. The input
# fields are the agent's own ToolInput; read one with tai tools schema <run-tool>.
tai agents run --help
```

## The seven agents

Each worked run below passes that agent's real `ToolInput` fields. A run needs the server up (`tai serve`) with a model configured for the deployment; the stream renders each `StreamEvent` frame — reasoning steps, tool-call/result steps, message deltas and finals, and a run-usage frame — as it arrives. A structured-output run adds a terminal structured final and nothing else: the stream carries no synthetic structured-output tool-call/result frame for the internal call that produced it.

### `tools_agent`

The plain/advanced LangGraph tools agent. It binds the named client tools to the model up front and runs them step by step. `spec_runnable` — its `ToolInput` advertises exactly the composable fields (`system_prompt`, `tool_names`, `presets`, `response_format`) an authored variant may bake.

```bash theme={null}
tai agents run tools_agent --input '{"user_message":{"content":"What is the current time in UTC?"},"tool_names":["current_time_info"]}'
```

### `langchain_deep_agent`

A deepagents/LangGraph-harness [deep agent](/concepts/deep-agents): planning, a per-thread scratch filesystem, skills, one level of nested sub-agents, and human-in-the-loop interrupts resumed with a LangGraph `Command`. Its scratch filesystem is a durable [sandbox](/concepts/sandbox) backend, so a run requires a sandbox provider — with none installed it fails loudly at `require_sandbox()`.

```bash theme={null}
tai agents run langchain_deep_agent --input '{"user_message":{"content":"Draft a short plan to organize a two-hour team workshop."}}'
```

When a run requests a `response_format` (a JSON Schema with a top-level `title`, and a non-empty `title` on every `oneOf` variant — missing either is a `ValueError`) but produces no structured output, **both faces raise rather than silently omitting the structured frame**: the JSON `run` face raises on drain, and the streaming face raises after the stream drains — unless the run paused on a pending interrupt, which takes precedence over the missing-structured raise.

### `claude_code`

Claude Code as a normal platform agent: it drives the Claude Agent SDK inside a [sandbox](/concepts/sandbox) session. The `claude_code` module ships in the already-baked `tai42-agents` package; enabling it is installing a sandbox provider and setting a `session_image` (a `...@sha256:` **digest**, never a bare tag). Under `sandbox-docker` (`tai plugins install tai42-sandbox-docker`) the runtime rides the pinned session image, with nothing extra to install. Under `sandbox-local` (direct-on-host, no isolation) the **operator** must first install the Claude runtime on the host — the `claude-agent-sdk` wheel (it bundles the Claude Code CLI, no separate Node.js) — because the server image stays lean. See [operate/sandbox](/operate/sandbox).

The SDK reads **exactly one** of two static, long-lived env vars: `ANTHROPIC_API_KEY` (the metered-key path) **or** `CLAUDE_CODE_OAUTH_TOKEN` (the subscription path, from the official `claude setup-token`). Both are compliant for every tai42 deployment: the SDK spawns the real `claude` binary — real Claude Code sessions, the sanctioned use of `setup-token`, not a raw-API path — and every tai42 deployment is single-tenant (one client, one deployment, one operator account). The choice is operator preference (subscription economics versus a metered key); setting neither, or both, fails the run loudly at start. Residual: the session's own shell can read the injected model credential for the session lifetime.

```bash theme={null}
tai agents run claude_code --input '{"user_message":{"content":"List the Python files in the workspace and summarize what each does."},"tool_names":["current_time_info"]}'
```

Its `ToolInput` fields are `user_message` (required), and optional `system_message`, `tool_names`, `skills`, `inline_skills`, `response_format`, `max_turns`, and `subagents`; read the exact live shape with `tai tools schema claude_code`.

A plain tool-face call is ephemeral and needs no Redis. A **threaded** run takes the shared park Redis for its per-workspace lease and async park. Human questions and long detached runs park through the same `agent_resume` machinery both deep-agent implementations share. A question answered while parked comes back as `{answer, reply_to, params}`: the continuation tool `agent_resume` is run with all three, and the agent's `ask` reads them as one object.

### `retrieval_tools_agent`

A tools agent that does not bind every tool up front: it embeds each tool's description into a vector store and exposes a `retrieve_tools` semantic-search tool, binding matches on demand. Useful when the tool set is large; cap the working set with `tools_limit`.

```bash theme={null}
tai agents run retrieval_tools_agent --input '{"user_message":{"content":"Generate a unique identifier for this record."},"tool_names":["generate_uuid","current_time_info"],"tools_limit":5}'
```

> [!NOTE]
>
> To give an agent the tools of an external MCP server, mount the server in the
> manifest's `mcp` section — its tools then register as ordinary tools any of these
> agents can bind by name through `tool_names`. See
> [Bring an MCP server](/guides/bring-an-mcp-server).

### `voting_agent`

Runs N voter LLMs in parallel over one prompt, then a judge LLM decides by majority vote (breaking ties with its own reasoning). Returns a `VotingOutput`; only the judge streams.

```bash theme={null}
tai agents run voting_agent --input '{"voter_message":{"content":"Is 97 a prime number? Answer yes or no with a one-line reason."},"judge_message":{"content":"Choose the best-justified answer."}}'
```

### `refine_agent`

An Evaluator↔Critic loop: the evaluator drafts, the critic reviews, and they alternate until the critic approves or the `max_iterations` budget is exhausted (a loud error, never an unapproved draft). Only the final approved pass streams.

```bash theme={null}
tai agents run refine_agent --input '{"evaluator_message":{"content":"Write a two-sentence tagline for a note-taking app."},"critic_message":{"content":"Approve only when it is under twelve words and concrete."},"max_iterations":3}'
```

### `vqa_agent`

Visual question answering: a single multimodal completion over an `image_url` (a public URL or a storage id) and a `query`. No tools, no graph.

```bash theme={null}
tai agents run vqa_agent --input '{"image_url":"https://example.com/chart.png","query":"What is the peak value?"}'
```

## Structured output and trusted-caller kwargs

Every agent above accepts a `response_format` — a JSON Schema with a **required top-level `title`** (the structured-output name), and every `oneOf` variant must carry a **non-empty `title`** of its own; a schema missing either raises a `ValueError`. When set, the run forces the model to emit matching output and returns the validated structured object as `state["structured_response"]`; a request that produces none raises loudly rather than falling back to text. The **authored schema reaches the model unchanged** — it is never stripped, widened, or restructured to fit a binder. The platform negotiates how it is bound, once per run, from what the model and its provider can carry:

* **Native tier** — a model that declares provider-native structured output, over a schema its native grammar can carry, is bound natively. The schema is adapted only minimally and value-preservingly where a native grammar requires it (a nullable type array becomes an `anyOf` of single-type members; a type-less `enum`/`const` of one JSON type gets that type); nothing else changes, and the set of values the schema accepts is identical.
* **Tool tier** — a schema holding a construct a native grammar cannot carry (a type-less `enum` whose members span more than one JSON type, an open map object) is bound through the model's **tool-calling path** with the authored schema unchanged, when the model accepts a forced tool call.
* **Refused** — a model that offers neither a native grammar for the schema nor forced tool choice is refused loudly before the request, naming the model, the provider, and the construct that could not be carried, so the author knows what to change.

On **Anthropic**, the native tier sends the authored schema to the model exactly as written (through the provider's `output_config`), with nothing added or rewritten. Its native grammar carries only what the provider's structured-output contract documents: plain enums (including `null` members), type arrays, `anyOf`, local non-recursive `$ref`/`$defs`, `const`, documented string `format`s, and `minItems` of 0 or 1 — but **every object must set `additionalProperties: false`**, and a schema may use at most **16 parameters with `anyOf` or type arrays** (counted across the whole schema) and **24 optional parameters**. A schema outside this contract is not carried natively — it takes the tool tier (or is refused, as above), named by the first construct or limit it breaks. Beyond those counted limits the provider enforces an internal compiled-grammar-size budget that **differs per model** and has no published number: the identical schema can answer natively on one model and be refused on another with `"The compiled grammar is too large, which would cause performance issues."` — that 400 surfaces as a loud error naming the node, provider and model, and shaping an over-budget schema is the deployment's. The native tier is not slower than the tool tier (measured: within a few percent, median-to-median, grammar-compile overhead negligible).

`base_url`/`api_key` in an agent's `llm_kwargs`/`embedding_kwargs` legitimately route to a caller-chosen model or embedding endpoint. Every agent that carries these kwargs leaves it a caller discipline — expose such an agent only to trusted callers, since an injected parent agent could redirect the call to a hostile endpoint and leak the key or context.

## Prompt caching

`system_content_kwargs` and `user_content_kwargs` merge content-block keys onto a message's text block — the former onto the system message, the latter onto the **last** user turn. With Anthropic's `{"cache_control": {"type": "ephemeral"}}` the key marks the end of the stable prompt prefix, so repeated calls read that prefix from cache instead of reprocessing it. On a thread (`thread_id`) each marked turn persists into history, but at the model call the platform keeps only the newest user-side mark, stripping the older ones from the outgoing request (stored history is untouched). So per-turn marking on a long thread always stays within the provider's per-request breakpoint cap (Anthropic: 4), and the whole growing history stays cacheable.

```bash theme={null}
tai agents run tools_agent --input '{"user_message":{"content":"What is the current time in UTC?"},"tool_names":["current_time_info"],"user_content_kwargs":{"cache_control":{"type":"ephemeral"}}}'
```

`tools_agent` honors both params. `voting_agent`, `langchain_deep_agent`, `retrieval_tools_agent` and `refine_agent` honor `user_content_kwargs` only — for voting/retrieval/refine the system prompt is internal or composed, and `langchain_deep_agent`'s caller-supplied prompt is handed to its factory as a plain string (never built as a content block), so in all four `system_content_kwargs` has no content block to ride and is **rejected loudly**; `vqa_agent` takes neither. On `langchain_deep_agent`, `user_content_kwargs` alongside a `resume` is likewise rejected — a resume carries no fresh user turn. On `voting_agent` the mark lands on the judge's final voter verdict, which varies per run, so it yields no reusable cache prefix.

> [!NOTE]
>
> The exact agent set and each agent's inputs are also listed on the [agents plugin page](/plugins/tai42/agents); the agents package's own documentation carries the per-agent reference detail. For authoring your own, see [Author an agent](/guides/author-an-agent).

## See also

* [Agents](/concepts/agents) — the `Agent` contract every ready-made agent implements.
* [Deep agents](/concepts/deep-agents) — sub-agents, skills, and strategies the deeper agents use.
* [Agents plugin](/plugins/tai42/agents) — the shipped agent set and its repository.
* [CLI reference](/reference/cli) — the full `tai agents` surface.


# WhatsApp to an agent
Source: https://docs.tai42.ai/guides/whatsapp-to-agent

Bridge a WhatsApp number to an agent through Twilio or the Meta Cloud API.

Bridge a WhatsApp number to an agent so a client's message runs an agent turn and
the answer comes back on WhatsApp. Two providers carry WhatsApp: **Twilio** and the
**Meta Cloud API**. The bridge is the same for both — only the channel plugin, its
env group, and the webhook wiring differ.

See [client conversations](/concepts/client-conversations) for the model this guide
configures.

## Prerequisite: mint and bind a least-privilege execution key

A conversation route runs its turn **as** an `execution_key` — an API-key identity,
not the client who texted. That key's live grants are the turn's entire authority,
so scope it to exactly what the agent needs and nothing more.

**1. Mint a scoped key**

Mint a key whose scopes are the least the agent's tools require. A non-admin
owner may grant only scopes it already holds; the new key is owned by you.

```bash theme={null}
tai keys create --user chat-bot --description 'WhatsApp chat agent' --scope read
```

**2. Bind it when you create the route**

The route's `--execution-key` binds that identity. You may bind your own
identity or a key you own; an admin may bind any key (a pass-role check). The
key must be evaluable by a background execution — a stored policy condition that
needs a request token is rejected at bind. The turn is bounded by the key's
**live** grants: attenuate the key and the next turn is denied, with no
revocation step on the route.

> [!WARNING]
>
> The turn can do whatever the execution key can do. Never bind an admin or a broadly
> scoped key to a route reachable from a messaging channel — a prompt-injected message
> would run as that key. Bind a purpose-built, least-privilege key.

## Pick a provider and wire it

Both providers use the same bridge and the same execution-key binding above. What
differs — the channel package and its env group, the webhook(s) to point at the
deployment, the `our_identity` format, and (on the Meta Cloud API) the rich-message
and 24-hour-window behaviour — lives on the plugin page:

> **[channel-twilio](/plugins/tai42/channel-twilio)**
>
> `CHANNEL_TWILIO_*`, the inbound and status webhooks, and the `whatsapp:`-prefixed
> sender as `our_identity`. Text only.

> **[channel-whatsapp](/plugins/tai42/channel-whatsapp)**
>
> `CHANNEL_WHATSAPP_*`, the single webhook with its `hub.challenge` handshake, the
> `phone_number_id` identity, plus interactive selects, media, and templates.

Once the channel is configured, create the route binding the texted number to the
agent, with `--channel` naming the provider and `--identity` its `our_identity`
(exact formats on the plugin pages):

```bash theme={null}
tai conversations create chat-line \
  --door channel --target-name chat --execution-key chat-bot \
  --channel <provider> --identity <our_identity>
```

The agent hears the message text by default. To tell it whether WhatsApp's 24-hour window is
still open (so it can say that a template follow-up is needed instead of a free-form reply),
build its message in `start_expr` from the turn's
[`reply_window`](/reference/conversation-bridge#route-targets-agent-or-tool):

```bash theme={null}
tai conversations create chat-line \
  --door channel --target-name chat --execution-key chat-bot \
  --channel <provider> --identity <our_identity> \
  --start-expr '{user_message: {content: (.message + "\n\n(reply window: " + .turn.reply_window.state + ")")}}'
```

`.turn.reply_window.state` is `open` while a free-form reply can reach the person, `closed`
after 24 hours with no message from them, and `none` on a channel with no window.

## Test it and add more numbers

Send a WhatsApp message to the configured number and watch the agent's reply come
back from that same number. Read one answer record by id:

```bash theme={null}
tai conversations get-message chat-line <message_id>
```

To take a thread off the flow and answer it yourself — or let the agent hand its own
conversation to a human — see [control mode and operator
messages](/concepts/client-conversations#control-mode-and-operator-messages).

**Multi-number** is just more rows: create another route with the same `--channel`
and a different `--identity` (a second Twilio sender, or a second `phone_number_id`
under one Cloud credential). Each identity resolves to its own route and agent, and
each reply leaves from the number that was texted. A `(channel, identity)` pair may
be claimed by only one route.

Delivery outcomes — including a `failed` record when WhatsApp rejects a send inside
or outside its 24-hour window (the turn's `reply_window` shows the window, but WhatsApp's
refusal stays the final word) — surface on the admin failed-delivery door:

```bash theme={null}
tai conversations failed
```

## See also

* [Client conversations](/concepts/client-conversations) — doors, routing, and
  delivery outcomes.
* [Conversation bridge reference](/reference/conversation-bridge) — every setting,
  the read doors, and the authorization model.
* [Use owned keys](/guides/owned-keys) — minting and capping the execution key.
* [Telegram / Slack to an agent](/guides/telegram-slack-to-agent) — the same bridge
  on other channels.


# TAI42 — the OS for AI tools
Source: https://docs.tai42.ai/index

An open-source runtime for MCP tools, agents, and workflows — the server that runs them.

**MCP defines how AI models call tools. TAI42 is where those tools
live.** The protocol doesn't say where a tool runs, who may call it, or
what happens when it needs OAuth, a schedule, or a human sign-off —
TAI42 is that missing server: Apache-2.0, self-hosted, where your
tools, agents, and existing MCP servers run as one system your team
operates.

```mermaid theme={null}
flowchart LR
    subgraph bring["You bring"]
        F["a Python function"]
        A["an agent"]
        E["an MCP server you already have"]
    end
    subgraph tai["TAI42 runs it — one self-hosted server"]
        OPS["access control · OAuth connectors · scheduling ·
        background execution · storage · monitoring ·
        human sign-off steps"]
    end
    subgraph use["Who calls it"]
        C["Claude Desktop · Cursor · any MCP client"]
        S["Studio UI · CLI · HTTP API"]
    end
    bring --> tai --> use
```

## One runtime instead of three stacks

Building serious AI tooling today means gluing three things: an agent
SDK for the agents, an MCP framework for the tools, and then the part
you end up writing yourself — access control, OAuth token handling,
background execution, scheduling, storage, monitoring, approval steps.
TAI42 ships all three as one runtime. You write the capability; the
operational layer is already there.

A tool is a plain decorated function; a one-file **manifest** declares
what the server loads (nothing loads implicitly — that's the point:
the manifest IS the system definition):

```python myapp/tools.py theme={null}
from tai42_contract.app import tai42_app

@tai42_app.tools.tool
def greet(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"
```

```yaml manifest.yml theme={null}
tools:
  - title: hello          # display/group name for this entry
    module: myapp.tools   # imported at startup; the decorator registers greet
    include: [greet]      # which functions from the module to expose
```

```yaml mount an existing server theme={null}
mcp:                      # servers you already run, mounted as-is
  - title: example-http
    config:
      url: https://mcp.example.com/mcp
  - title: example-stdio
    config:
      command: uvx
      args: [some-mcp-server]
```

`tai serve --manifest-path manifest.yml` — and `greet` is an MCP tool
callable from Claude Desktop, Cursor, the bundled web console (the
Studio), the CLI, or an agent. The auth middleware, the OAuth token refresh, the cron wrapper,
the job queue, the audit trail you were about to write around it —
already running.

**Already have an MCP server?** TAI42 is built on FastMCP and speaks
standard MCP — any server you already run mounts as-is (over HTTP, a
unix socket, or as a stdio process the runtime launches, per the
`mcp:` tab above); its tools appear next to your own, behind the same
auth and monitoring. Nothing needs porting. And when a tool is
sensitive, it can pause for **human sign-off** — answered from the
Studio inbox or a connected chat channel (Slack, Telegram, WhatsApp).

## The server is alive

With plain MCP frameworks, your server is a build artifact — change a
tool, restart the process. A TAI42 server is operated **live**: reload a
tool in place, replace the manifest across every worker process at
once, re-probe and re-attach an external MCP server that was
down, refresh config in place — no restart. Each of these operations is
declared once and exposed three ways — HTTP API, CLI command, and
optionally as an MCP tool your agents can call (an admin chooses which
ones) — so the UI, your terminal, and your agents always drive the same
thing.

## What's in the box

> **[Tools](/concepts/tools-and-extensions)**
>
> A decorated function or a mounted server's tool. Wrap one with an
> **extension** (rate-limit it, transform it), save a configured
> variant as a versioned **preset**.

> **[Agents](/concepts/agents)**
>
> An included agent framework — you author an `Agent` class in
> Python, the runtime runs it and streams every step (messages,
> reasoning, tool calls) live. Models ride standard LangChain
> providers (OpenAI, Anthropic, …) with your own keys, set in
> config. Callable exactly like any tool.

> **[The operational layer](/concepts/live-operations)**
>
> Key-based identities with scoped policies checked on every
> request, OAuth connectors, scheduling, background execution,
> storage, monitoring, human sign-off — supplied, not built by you.

It's for developers and platform teams who've outgrown a
localhost MCP script and want a system their team operates — on their
own machines, with their own data. Every subsystem plugs in against
shared open interfaces (storage, background-job backends, OAuth
connectors, and chat channels are all swappable plugins), and each install is a self-contained Python server
you run with `uv` or Docker.

## Start here

> **[Install](/getting-started/installation)**
>
> Install from PyPI and boot a working server in minutes.

> **[Quickstart](/getting-started/quickstart)**
>
> Serve the hello example and call a tool over MCP.

> **[Mental model](/getting-started/mental-model)**
>
> How the runtime fits together, in one page.

> **[Marketplace](/marketplace/index)**
>
> Browse plugins and install into a running server.


# Claude Desktop
Source: https://docs.tai42.ai/integrations/claude-desktop

Connect Claude Desktop to a running server.

Connect Claude Desktop to a running server with an MCP server config entry.

Claude Desktop launches MCP servers over stdio and lists their tools in the app. Add a `tai` entry to its config, and Claude Desktop starts the server and connects on launch.

## Add a config entry

Edit Claude Desktop's `claude_desktop_config.json` (Settings → Developer → Edit Config) and add a `tai` server under `mcpServers`. Claude Desktop launches the command and speaks MCP over its standard streams.

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "tai": {
      "command": "tai",
      "args": ["serve", "--transport", "stdio", "--manifest-path", "/path/to/manifest.yml"],
      "env": {
        "TAI_MANIFEST_PATH": "/path/to/manifest.yml"
      }
    }
  }
}
```

Use an absolute path to `tai` if it is not on Claude Desktop's `PATH`, and an absolute `--manifest-path`. Restart Claude Desktop to load the entry.

**1. Confirm the server runs standalone**

Start it once in a terminal to check the manifest and environment before wiring the client.

```bash theme={null}
tai serve --transport stdio --manifest-path /path/to/manifest.yml
```

**2. Add the config entry**

Add the `mcpServers` block above and set an absolute command path and manifest path.

**3. Restart and verify**

Restart Claude Desktop; the server's tools appear in the app's tool list.

> [!NOTE]
>
> Claude Desktop uses the stdio transport. To reach a server running over HTTP instead — a remote or shared instance — use a generic MCP client entry; see [MCP clients](/integrations/mcp-clients).

## See also

* [MCP clients](/integrations/mcp-clients) — the transport options and the HTTP config shape.
* [Deploy](/operate/deploy) — the manifest and environment the server loads.
* [Expose a private tool set](/guides/private-tool-set) — scope Claude Desktop to a tool subset.


# Cursor
Source: https://docs.tai42.ai/integrations/cursor

Connect Cursor to a running server.

Connect Cursor to a running server with an MCP server config entry.

Cursor reads MCP servers from an `mcp.json` file and lists their tools in the editor. Add a `tai` entry — a launch command for a stdio server, or a URL for an HTTP one.

## Add a config entry

Put the entry in `~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` in a project for that project only. Add a `tai` server under `mcpServers`.

```json stdio theme={null}
{
  "mcpServers": {
    "tai": {
      "command": "tai",
      "args": ["serve", "--transport", "stdio", "--manifest-path", "/path/to/manifest.yml"]
    }
  }
}
```

```json http theme={null}
{
  "mcpServers": {
    "tai": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

Use an absolute path to `tai` and to the manifest for the stdio entry. For the HTTP entry, run the server yourself (`tai serve --transport http --port 8000`) and point the URL at it.

> [!NOTE]
>
> A server behind [access control](/guides/access-control) requires an API key. For the stdio entry, set `TAI_API_KEY` in an `env` block on the server; for the HTTP entry, supply it in the client's request headers.

## See also

* [MCP clients](/integrations/mcp-clients) — the transport options in depth.
* [Deploy](/operate/deploy) — running the server over HTTP.
* [Expose a private tool set](/guides/private-tool-set) — scope Cursor to a tool subset.


# Integrations
Source: https://docs.tai42.ai/integrations/index

Connect MCP clients to a running server, and connect the server to the apps your team already uses.

Connect MCP clients to a running server. Each client page carries a config
snippet against the server's published transport.

## MCP clients

> **[Claude Desktop](/integrations/claude-desktop)**
>
> Config entry for Claude Desktop.

> **[Cursor](/integrations/cursor)**
>
> Config entry for Cursor.

> **[MCP clients](/integrations/mcp-clients)**
>
> Any MCP client.

## Connect the server outward

To connect the server to the apps your team already uses — Gmail, Calendar,
Drive, Jira, Confluence, and more — install a
[connector](/concepts/connectors) from the [Plugins section](/plugins). The
connector model is [Connectors](/concepts/connectors); the end-to-end setup is
[Connect an OAuth provider](/guides/connect-an-oauth-provider).


# MCP clients
Source: https://docs.tai42.ai/integrations/mcp-clients

Connect any MCP client.

Connect any MCP client to a running server over its published transport.

The runtime is a standard MCP server, so any MCP client connects to it the same way it connects to any other — over the transport the server publishes. The only choices are which transport the server runs and how the client addresses it.

## Match the transport

Start the server on the transport your client speaks (see [Deploy](/operate/deploy)):

* **stdio** — the client launches the server as a subprocess and speaks over its standard streams. Configure the client with a command.
* **HTTP / streamable-http / SSE** — the client connects to a URL. Configure the client with the server's address.

```bash theme={null}
tai serve --transport stdio                          # client launches the server
tai serve --transport http --host 0.0.0.0 --port 8000   # client connects to a URL
```

## Configure the client

Most MCP clients read a JSON config that maps a server name to either a launch command (stdio) or a URL (HTTP).

```json stdio theme={null}
{
  "mcpServers": {
    "tai": {
      "command": "tai",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}
```

```json http theme={null}
{
  "mcpServers": {
    "tai": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

> [!NOTE]
>
> A server behind [access control](/guides/access-control) requires an API key. Supply it the way your client passes credentials — for an HTTP transport, an `Authorization` header; for a stdio server, the `TAI_API_KEY` environment variable on the launched process.

## Scope a client to a subset

To expose only a subset of tools to one client, publish them as a sub-MCP app and point the client at its slug. See [Expose a private tool set](/guides/private-tool-set).

## See also

* [Claude Desktop](/integrations/claude-desktop) — the config entry for Claude Desktop.
* [Cursor](/integrations/cursor) — the config entry for Cursor.
* [Transports](/concepts/transports) — the transport options in depth.
* [Deploy](/operate/deploy) — running the server for real.


# Advisories
Source: https://docs.tai42.ai/marketplace/advisories

How a server hears about bad versions, and the poll setting.

An advisory flags affected versions of a listing with a severity and a
summary. Your server checks advisories for the plugins it has installed — at
install time, on demand, and on a background poll you control.

## Check on demand

```bash theme={null}
tai plugins advisories
```

Lists the advisories affecting your installed plugins, from the server's
cached advisory state.

## At install time

Every install and update checks the registry before anything changes: a killed
version cannot be resolved at all, and a non-withdrawn critical advisory
against the requested version refuses the install. Lesser advisories ride the
install response rather than blocking it.

## The background poll

A running server polls the registry for advisories affecting its installed
plugins. The poll is deliberately visible:

| Setting | Default | Meaning |
| - | - | - |
| `MARKETPLACE_ADVISORIES_POLL` | `true` | Poll the registry for advisories on installed plugins. |
| `MARKETPLACE_ADVISORIES_INTERVAL_S` | `3600` | Seconds between polls. |
| `MARKETPLACE_URL` | `https://marketplace.tai42.ai` | The registry the server talks to. |

At startup the server logs the poll target URL, so the outbound call is never
silent. The poll fetches advisories only — nothing about your server is sent
beyond the request itself. Disable it with one env var:

```bash theme={null}
MARKETPLACE_ADVISORIES_POLL=false
```

With the poll off, install-time checks and `tai plugins advisories` still work —
they are direct requests you make, not background traffic.

## See also

* [The marketplace model](/concepts/marketplace) — advisories and the kill switch.
* [Install a plugin](/marketplace/install) — the install-time check.
* [Config and secrets](/concepts/config-and-secrets) — how settings resolve.


# Author plugin docs
Source: https://docs.tai42.ai/marketplace/authoring-docs

The docs contract every published plugin follows: an in-package docs tree, required front matter, and the safe subset third-party pages are held to.

A published plugin ships its own documentation inside the package. The marketplace
extracts that docs tree at publish time and stores it; the docs site reads it back
and renders one page per listed plugin under [Plugins](/plugins). You never open a
pull request against the docs site — publishing the plugin publishes its docs.

This page is the single contract those docs follow. The same rules are enforced at
three points from one implementation — the marketplace ingest gate, the monorepo
CI gate, and the docs-site generator — so a page that publishes renders, and a page
that violates the contract is refused at the earliest gate rather than shipping
broken.

## The docs tree

Docs live in a `docs/` directory inside the package, alongside the code:

```
your_plugin/
  tai-plugin.yml
  docs/
    index.mdx          # required — the plugin's main page
    <more>.mdx         # optional — extra pages
    images/
      screenshot.png   # raster images only
```

* **`docs/index.mdx` is required.** It is the plugin's landing page. The docs site
  renders your body beneath a generated header (the install line, the declared
  permissions, and the list of items the plugin provides — all read from your
  `tai-plugin.yml`, never hand-written).
* **Only `.mdx` pages under `docs/`, and raster images under `docs/images/`.** Any
  other file type is refused. Images must be raster — `.png`, `.jpg`, `.jpeg`,
  `.gif`, or `.webp`. **SVG is refused** for every plugin: an SVG is active content
  (a script-injection surface), not an inert image.
* **Links and image references must resolve within the tree.** A relative link to a
  page or image that is not in `docs/` fails the gate.

## Front matter

Every `.mdx` page begins with a front-matter block of exactly `title` and
`description` — nothing more, nothing less:

```mdx theme={null}
---
title: "Standard toolbox"
description: "The tools and extensions this package provides."
---

Your page body starts here.
```

Both values are single-line plain strings. They may not contain quotes,
backslashes, control characters, or the `---` fence marker — those values are
re-emitted into the generated page's own front matter, so a fence-breaking
character would corrupt it. `title` and `description` from `docs/index.mdx` become
the plugin page's title and description (and feed the site's `llms.txt` index).

## First-party vs. third-party pages

The mdx a page may use depends on who publishes it:

* **First-party plugins** (namespace `tai42`) may use the full Mintlify component
  set in their bodies.
* **Third-party plugins** are held to a **safe markdown subset**: no raw HTML or JSX
  tags, no `import`/`export`, no `{ }` expression containers, and link/image targets
  restricted to `http(s)` or an in-tree relative path (`javascript:` and `data:`
  are refused). The docs site renders third-party content, and this subset is what
  keeps a published page from carrying an execution surface onto the site.

The rule is the same one the runtime enforces; there is no separate docs-only
policy to track.

## What to write, and what to leave central

A plugin page is a **thin provider page**. Document what is specific to your plugin —
the items it provides, its settings, the extras to install. Do not re-document a
platform feature your plugin plugs into; link to its central page instead. A tool
extension links to [Tools and extensions](/concepts/tools-and-extensions); a
connector links to [Connectors](/concepts/connectors); and so on. The feature is
documented once, centrally; your page is the provider's own reference.

## See also

* [The marketplace model](/concepts/marketplace) — listings, items, versions, advisories.
* [Publish and install](/marketplace/install) — getting a plugin into a running server.
* [Plugins](/plugins) — the rendered result: one page per listed plugin.


# Browse and search
Source: https://docs.tai42.ai/marketplace/browse

Find plugins by the items they carry — CLI, Studio, or the web.

Search the marketplace at item level: the query matches the tools, extensions,
and agents a plugin carries, and the result tells you which plugin to install.

## Search from the CLI

`tai plugins search` queries the registry through your server. Filter by item
kind, category, and tag, and sort by downloads, last update, or name.

```bash theme={null}
tai plugins search uuid --kind tool
tai plugins search --category productivity --sort downloads
tai plugins search --tag http --tag cache
```

`--tag` is repeatable — pass it once per tag. `--sort` accepts `downloads`,
`updated`, or `name`. `tai plugins categories` lists the registry's controlled
category vocabulary — the values the `--category` filter accepts.

Fetch one listing's full picture — its items and versions — by its
`namespace/name` ref:

```bash theme={null}
tai plugins info tai42/toolbox
```

## Browse in the Studio

The Studio's Marketplace screen drives the same search with facet chips for
kind, category, and tags and a sort control, and opens a plugin's detail —
items, versions, description, and repository link — with install a click away.
See [the screens](/studio/screens).

## Browse on the web

A public browse-only marketplace web site accompanies the registry — search
and read there without a running server; installing always happens from a
server. The site is a static bundle behind an nginx proxy that forwards `/api` to
a registry. Its hostname and that upstream are deployment configuration: the
container reads the upstream from the runtime variable `API_UPSTREAM`, and the
build-time client variables are documented in
[`tai-marketplace-web`](https://github.com/tai42ai/tai-marketplace-web#environment).

> [!NOTE]
>
> Search is item-level, install is plugin-level: a result row names the item
> you found and the listing that ships it.

## See also

* [The marketplace model](/concepts/marketplace) — listings vs items.
* [Install a plugin](/marketplace/install) — from ref to loaded tools.
* [CLI reference](/reference/cli/index) — the full `tai plugins` surface.


# Marketplace
Source: https://docs.tai42.ai/marketplace/index

Browse the plugin index and install into a running server.

Browse the ecosystem's plugin index and install a plugin into a running server
in one command — from the CLI, the Studio, or the public site.

> **[The marketplace model](/concepts/marketplace)**
>
> Listings, items, versions, and advisories.

> **[Browse and search](/marketplace/browse)**
>
> Find plugins by the items they carry.

> **[Install a plugin](/marketplace/install)**
>
> Install, update, and uninstall server-side.

> **[Advisories](/marketplace/advisories)**
>
> Hear about bad versions, and the poll setting.


# Install a plugin
Source: https://docs.tai42.ai/marketplace/install

Install, update, and uninstall marketplace plugins server-side.

Install a marketplace plugin into a running server in one command. Install is
a server-side operation: the server itself resolves the listing, installs the
package, patches its manifest, and reloads — so the CLI, the Studio, and the
HTTP API all drive the same flow.

**1. Find the plugin ref**

Every listing is addressed as `namespace/name`. Find it with
[search](/marketplace/browse) — `tai plugins search uuid` names the listing
that ships the item you want.

**2. Install**

```bash CLI theme={null}
tai plugins install tai42/toolbox
```

```bash HTTP theme={null}
curl -X POST https://<your-server>/api/marketplace/install \
  -H "x-api-key: $TAI_API_KEY" \
  -H "content-type: application/json" \
  -d '{"ref": "tai42/toolbox"}'
```

Pin a version with `--version` (or a `version` field in the body); with no
version the server resolves the **newest version compatible with the core it
is running** — a core-aware pick, so an install never lands a version your
running core cannot load. A version you pin explicitly is still checked
against the server's installed tai42-contract — one that does not fit refuses
to install, and the error names the mismatch.

**3. Verify**

```bash theme={null}
tai plugins installed
```

The plugin appears with its installed version, and its items are live —
its tools list under `tai tools`, its extensions under `tai extensions`.

## What install does

1. Resolves the ref against the registry — with no pinned version, the newest
   version compatible with the server's installed tai42-contract (core-aware
   resolution) — and checks advisories. A version that does not fit the
   contract, one that is killed, or one under a non-withdrawn critical advisory
   refuses before anything changes.
2. Installs the resolved version by source: a GitHub-sourced plugin downloads
   the release tarball, verifies its SHA-256 against the digest the registry
   recorded at ingest, and installs only that verified file — a re-pointed tag
   is refused; a PyPI-sourced plugin pins the exact version (`package==version`)
   and relies on PyPI's file immutability for that version.
3. Patches the server [manifest](/concepts/manifest) once per provided item — a
   tool module lands under `tools`, an extension module under
   `extensions_modules`, and so on, exactly as the plugin's
   `tai-plugin.yml` declares.
4. Reloads the server, and records the marketplace ref and version locally.

If any step fails, the whole install aborts and the error names the step —
never a half-installed plugin. The manifest, registration, and install record
fully revert; package changes the underlying pip run already made are pip's own
boundary.

Registry-dispatched items — tools, agents, extensions, storages, and a channel's
registration and outbound delivery — are live the moment that reload lands, and
so are the HTTP surfaces. A **router** or **middleware** plugin, and a Tier-2
channel's inbound webhook route, come live on the next reload / config-apply: the
[epoch rebuild](/concepts/live-operations#the-mutation-pipeline) re-imports the
plugin package and its route-sibling modules and re-registers the declared routes,
so a route-carrying plugin is serving on the same reload as the rest — no full
process restart required (Tier-1 confirm/external channels register no inbound
route). See
[self-hosted upgrades](/self-hosted/upgrades#runtime-installed-plugins).

> [!NOTE]
>
> Install writes into the server's own environment and manifest. On a self-hosted
> deployment, keep both on persistent storage — the plugin-prefix directory and
> the manifest file — so a container recreation does not drop the plugin. See
> [the persistent mounts](/self-hosted/quickstart#the-persistent-mounts).

## Provide required environment

Some plugins need environment values to run — an MCP server's `!ENV` markers, an
OAuth [connector](/concepts/connectors)'s client id and secret. The **server**
decides what a given install requires: the install preview computes the listing's
`required_env` — each variable as `{name, secret}` — and the `missing_env` still
absent from this server's environment. Every surface reads that one server-computed
answer; none of them re-derives it.

* **CLI** — `--env KEY=VALUE` supplies a value, and it is the only flag that
  carries a value. `--secret KEY` is a bare mark (a key, no value) that keeps that
  key masked in the environment and out of logs; a value you want hidden is still
  passed with `--env KEY=VALUE` and additionally marked with `--secret KEY`. A
  connector's client secret is auto-marked, so the mark is optional there. Both
  flags are repeatable.
* **Studio** — the install dialog lists the missing variables, prompts for them,
  and seeds each secret toggle from `required_env`, so you fill exactly what the
  server says is missing.

```bash theme={null}
tai plugins install acme/connector-example \
  --env ACME_CLIENT_ID=... \
  --env ACME_CLIENT_SECRET=... \
  --secret ACME_CLIENT_SECRET
```

An install that would leave a required variable unresolved is refused before
anything is written, and the error names the variables. `--dry-run` shows the
delivery and the required env without installing.

## Mount the routes

A plugin that mounts HTTP routes — a `router` item, or a `channel` with an inbound
webhook — [declares](/concepts/marketplace#declared-http-routes) them relative to a
`base` prefix, and install is where you see the resulting absolute paths, remap the
prefix if you want, and accept any route the plugin serves without a credential.

![The marketplace install dialog showing the resolved routes for a route-carrying plugin, a base-prefix input to remap them, and a checkbox accepting the public routes served without authentication.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/marketplace-install-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=cf39f88cc4571142d88d8a8545761b7a)

The Studio install dialog: each route resolved to its full path, a per-item base to remap the prefix, and the acceptance checkbox for the routes served without authentication.

**Preview first.** Ask the server what a given install would mount — no side
effects, nothing written:

```bash CLI theme={null}
tai plugins install acme/alerts-relay --dry-run
```

```bash HTTP theme={null}
curl -X POST https://<your-server>/api/marketplace/install/preview \
  -H "x-api-key: $TAI_API_KEY" \
  -H "content-type: application/json" \
  -d '{"ref": "acme/alerts-relay"}'
```

The preview resolves each route to its full `/api/...` path, flags which are public,
and lists any collision with a route the core or an already-installed plugin owns.
`--dry-run` prints that table and exits non-zero if anything collides.

**Remap the base.** Every route-carrying item mounts under a default `base`; move it
with `--mount item=base` (repeatable), or a `route_mounts` object in the body. The
whole item's routes shift together — only the `base` moves, never the `/api/` root
or a route's own path:

```bash CLI theme={null}
tai plugins install acme/alerts-relay --mount relay=alerts/relay-2
```

```bash HTTP theme={null}
curl -X POST https://<your-server>/api/marketplace/install \
  -H "x-api-key: $TAI_API_KEY" \
  -H "content-type: application/json" \
  -d '{"ref": "acme/alerts-relay", "route_mounts": {"relay": "alerts/relay-2"}}'
```

**Accept the public routes.** A route the plugin declares `public` answers
**without authentication** — an inbound webhook has to. Install refuses until you
say so: without acceptance it returns `400 PUBLIC_ROUTES_NOT_ACCEPTED` and lists the
routes, so opening an unauthenticated door is always a deliberate step. Accept with
`--accept-public-routes` (or `"accept_public_routes": true`). On an **update**, only
a route that is newly public — not one you already approved on the installed
version — needs accepting again.

The install receipt returns the mounted routes — each item, full path, methods, and
public flag — so you can confirm what opened where.

### A collision is a remap

Two plugins can never own the same route. If a plugin's resolved paths clash with a
route the core or another installed plugin already owns, install stops with
`409 ROUTE_COLLISION` and names the clashing paths; nothing is installed. The remedy
is to remap the colliding item onto a free `base` and install again:

```bash theme={null}
tai plugins install acme/alerts-relay --mount relay=alerts/relay-b
```

The same check runs on the manifest patch, so a collision is caught in pre-flight,
before any package is fetched.

**Mounts persist across restart.** The server stores each item's chosen `base`
alongside the install record, so a reload or a container recreation brings every
route back up at the same path — a remapped route stays remapped, with no re-entry
of the mount. Keep the install record and manifest on
[persistent storage](/self-hosted/quickstart#the-persistent-mounts) so a recreated
container does not lose them.

## Update

```bash theme={null}
tai plugins update tai42/toolbox
```

`tai plugins installed` shows update availability per plugin; update resolves
the new version and runs the same install flow. Pin a target with `--version`,
or omit it for the latest.

To move the whole installed roster onto versions compatible with the running
core in one step — the flow after a [self-hosted image upgrade](/self-hosted/upgrades#runtime-installed-plugins):

```bash theme={null}
tai plugins upgrade --all
```

## Uninstall

```bash theme={null}
tai plugins uninstall tai42/toolbox
```

Uninstall reverses the manifest patch, reloads to converge the live
registration with the stripped manifest, and then uninstalls the package. It
converges: a failure names exactly what remains, and re-running uninstall
completes the removal.

> [!WARNING]
>
> Install, update, and uninstall mutate the running server's environment.
> Scope the `/api/marketplace/*` routes with
> [access control](/concepts/access-control) like any other mutating surface.

## From the Studio

The Marketplace screen's plugin detail offers the same install, update, and
uninstall actions with progress surfaced in place — it drives these routes.

## See also

* [Browse and search](/marketplace/browse) — find the ref.
* [Advisories](/marketplace/advisories) — what a killed version means.
* [The manifest](/concepts/manifest) — what the patch touches.


# Accounts and sign-in
Source: https://docs.tai42.ai/operate/accounts

Give humans logins with the Postgres accounts provider.

[Accounts](/concepts/accounts) are the human half of identity: an email and
password, a session, and a role. The **`tai42-accounts-postgres`** plugin
provides them — it stores email/password accounts on Postgres, mints sessions,
drives invites, and contributes the Studio's Users screen.

> **[Postgres accounts](/plugins/tai42/accounts-postgres)**
>
> Install and wire the store, run its migrations, create the first admin, and
> invite the team — with the `TAI_ACCOUNTS_*` session and login-limit settings.

## What every accounts deployment shares

* **Accounts ride on [access control](/concepts/access-control).** Turn it on
  (`ACCESS_CONTROL_ENABLE=true`) and name the provider in
  `ACCESS_CONTROL_AUTH_PROVIDERS`. Keep `redis` in the list so minted API keys
  keep working next to human sessions.
* **A sign-in does not provision authority.** A logged-in human resolves to a
  user id, and until a policy exists for that id every protected route denies the
  request. Provision the policy first, then invite the person — the
  [access-control guide](/guides/access-control) writes the jq policy end to end.
* **Provider order matters.** Members of `ACCESS_CONTROL_AUTH_PROVIDERS` are
  tried in order and fail closed: an outage in an earlier member denies the
  members after it.
* **Every admin principal counts.** The platform keeps at least one enabled admin
  principal — an account on the `admin` role, the owner from setup, an admin
  service principal — and refuses the change that would leave none. Demoting your
  last admin account is allowed while the owner is still enabled. See
  [the last enabled admin stays](/concepts/permissions#the-last-enabled-admin-stays).
* **A member's role is read from access control.** The Members page shows the role
  every login of the member holds, **No role** when that member's access was set
  directly rather than from a role, or **Mixed roles** with each login's own role
  when the member's logins hold different roles. A provider's change-role action gives every
  login of the member one role, which clears it.

## See also

* [Accounts](/concepts/accounts) — the model behind these routes.
* [Access control](/concepts/access-control) — the policy every identity resolves to.
* [API-key machine identity](/plugins/tai42/identity-redis) — token auth for machines (not human sign-in).
* [The admin console](/studio/admin-console) — where the Users screen lives.


# Task backends
Source: https://docs.tai42.ai/operate/backends

Choose arq, Celery, or RQ as the backend that runs queued, scheduled, and agent work.

A [backend](/concepts/backends) is where work runs when it does not run inline:
queued tool calls, schedules, and agent turns. Three shipped backends implement
the same contract — pick one, name its package in the manifest, and run a worker
process against it.

| Backend | Package | Broker | Extra processes | When to pick it |
| - | - | - | - | - |
| arq | `tai42-backend-arq` | Redis | `worker` | The default: Redis-only, no separate broker. What the distribution bundle selects. |
| Celery | `tai42-backend-celery` | RabbitMQ (broker) + Redis (results, schedule) | `worker`, `beat`, `flower` | You already run RabbitMQ, or you need beat and flower. |
| RQ | `tai42-backend-rq` | Redis | `worker`, `beat`, `dashboard` | Redis-only like arq, with a scheduler and the RQ dashboard. |

> [!NOTE]
>
> Every registered backend needs the [worker bus](/concepts/worker-bus) and a
> shared [hooks registry](/concepts/hooks#managing-hooks-live): `TAI_BUS_REDIS_URL`
> and `HOOKS_REDIS_URL` must be set (each falls back to `TAI_DEFAULT_REDIS_URL`), or
> boot is refused. The backend process matches the events it raises against its own
> hooks registry, and an in-memory one holds none of the hooks registered through
> the server. Stacks sharing one Redis must also diverge on `TAI_BUS_NAMESPACE`
> (default `tai`).

## Install and run one

Each backend's package, its `backend_module` manifest key, its `<PREFIX>_*`
settings, the worker/beat/dashboard commands it accepts, and its
contract-coverage quirks live on the plugin page:

> **[backend-arq](/plugins/tai42/backend-arq)**
>
> `ARQ_*` settings and the single `worker` process.

> **[backend-celery](/plugins/tai42/backend-celery)**
>
> `CELERY_*` settings, beat and flower, and the prefork concurrency caveat.

> **[backend-rq](/plugins/tai42/backend-rq)**
>
> `RQ_*` settings, worker, beat, and the dashboard.

## See also

* [Backends](/concepts/backends) — the contract all three implement.
* [Manage a fleet](/operate/manage-a-fleet) — read the live worker census.
* [Schedule a tool](/guides/schedule-a-tool) — put work on a schedule.


# Back up and restore
Source: https://docs.tai42.ai/operate/backup-and-restore

Back up and restore stored state.

Back up and restore a server's stored state.

The runtime exports its stored state as a backup document and imports it back. Each backup is composed of named **sections** — access-control policies, presets, and whatever else the host and its plugins register. You choose which sections to export and which to import; nothing is all-or-nothing.

## List the sections

See which sections are registered and can be exported or imported.

```bash theme={null}
tai backup sections
```

## Export

Export the named sections as a backup document. The document prints to stdout — redirect it to a file to save it. `--section` is repeatable.

```bash theme={null}
tai backup export --section access_control > backup.json
```

## Import

Import selected sections from a backup document file. Name each section to apply; a section in the file that you do not name is left untouched.

```bash theme={null}
tai backup import backup.json --section access_control
```

> [!WARNING]
>
> Importing a section applies its payload over the live state. Export the current state first so you have a document to roll back to, and import only the sections you mean to restore.

### Skip or overwrite

An import runs under one **mode**, applied per record: `skip` (the default) or `overwrite`. The mode is decided against each record's **natural key** — the field that identifies it within its section:

* Under `skip`, a record whose key already exists on the server is left exactly as it stands — its live value is never replaced — and only records with a new key are created.
* Under `overwrite`, an existing record is upserted from the backup; new records are still created.

The natural key is per section: a hook by its `name`, a topic verifier by its `topic`, a template by its path, a sub-MCP app by its slug, a stored connection by its id, an access-control route by its url. New records are created under both modes; the mode only decides what happens when a key collides with a live one.

Mode is a property of the HTTP import door, not the CLI: `POST /api/backup/import` takes a `"mode"` field in its body (an unrecognized value is a `400`). The `tai backup import` command sends no mode, so **the CLI always restores in the default `skip`** — the non-destructive choice. To overwrite, call the door with `"mode": "overwrite"`.

### The sections that ignore mode

A few sections do not key per record, so mode does not apply:

* **`manifest`** restores as a whole document — a single manifest always replaces the live one, through the mutation pipeline below.
* **`env`** **merges**: every key in the backup is applied, updating a key that exists and adding one that does not. It never removes a live key the backup omits.
* **API-key tokens** (inside `access_control`) are **never overwritten**, under either mode. A restore mints brand-new keys for absent user ids and surfaces each plaintext in `new_api_keys` to redistribute; a user id already provisioned keeps its live key and is reported as skipped. To replace one, revoke that user id's key first, then re-import — the mint refuses to overwrite an existing identity.

### Access-control routes are canonical

The route table holds every url in its canonical form (each segment decoded once, slashes collapsed, dot segments resolved, no trailing slash), and an `access_control` import matches an archive url against the live table by that form. Two archive urls that reduce to one canonical route (`/api/x` and `/api//x/`) would overwrite each other, so the whole section is **refused before its first write**, the collision named in the section's `errors`; an archive url with no canonical form is refused the same way. Correct the archive and import again.

A deployment refuses to **boot** while its route table holds a row that is not in canonical form, naming every such row. Every route door and the import write the canonical form, so such a row comes from a write made directly to the database, and no door can reach it while the boot refuses. Correct it there: in the skeleton database's `access_control_routes` table, set each named row's `url` to its canonical form — or delete the row when its canonical url is already in the table, or when the url has no canonical form at all — then start the deployment again.

An `access_control` import invalidates every worker's cached policy decisions once when it ends, and a `sub_mcp` import invalidates them after each restored app, so a restored route, policy or mount is enforced on the next request.

### The accounts archive

The Postgres accounts provider registers its own `accounts` section: the account
roster (email, password hash, disabled flag, creation time), never sessions or
pending invites. Its archive format is **version 2**, which carries no role — a
member's role lives in their access-control policy, restored by the
`access_control` section. An archive of **version 1** is refused before anything is
written, and the section's report names the version: recreate the archive from a
deployment on the current baseline, then import it.

### API keys and the identity store

An api key spans two stores: its policy — scopes, condition, fingerprint, and owner — lives in Postgres, while the secret exists only as a hash on the key's identity record, which the [identity provider](/concepts/access-control) keeps in Redis. An export carries the policy alone and never any key material, which is why a restore re-mints keys and returns each new plaintext once in `new_api_keys`.

Restore the two stores together: bring Redis and Postgres back from snapshots of the same moment, or import `access_control` onto an empty Postgres so every key is minted fresh. A restore that lands Postgres rows on a flushed identity store leaves those keys with a policy row but no identity — an **orphaned** state the platform names and clears rather than stranding:

* The key listing marks each orphaned row `orphaned: true`, so you can find them.
* A restore re-mints an identity for each orphaned row under the same user id, leaves its policy — scopes, condition, fingerprint, and owner — untouched, and returns the new plaintext once in `new_api_keys`. A user id whose identity is still present is skipped, as above.
* Revoking an orphaned key clears its policy row.
* Minting a key on an orphaned user id is refused until you re-import the backup to re-mint it, or revoke it.
* The setup door does not re-open: once the owner principal exists in Postgres, `POST /api/setup` answers `409` even when every key is orphaned. To recover the owner's access, re-import an `access_control` export — it re-mints every orphaned key, including the owner's. Without an export, run `tai setup --recover --token <setup token>` on the deployment host: it re-mints **only** the owner's key onto the surviving policy row (same fingerprint, scopes, and owner; a fresh identity record; the plaintext printed once), and refuses while an owner key still authenticates. Revoke or re-mint the other orphaned keys through `tai keys` afterward.

### The import report

Each section returns a report: `created`, `updated`, and two distinct skip counts. `skipped_existing` counts records left untouched because their key already existed under `skip` — a clean, expected skip, not a failure. `errors` (with a matching `skipped`) counts records **rejected** — a malformed entry, an unsafe path, a token bound to a scope that never materialized, a token whose policy data carries `disabled` (a key has no disabled state; it is revoked), a token minted fresh with neither a scope nor a condition (it would grant nothing), a route mapping a URL that a route declared public serves — each named in the report so one bad record never silently drops or aborts the rest.

Restoring the `manifest` or `env` section applies **live and fleet-wide**: the import runs the same [mutation pipeline](/concepts/live-operations#the-mutation-pipeline) a config change does — validate, persist, reload the calling process, then broadcast on the [worker bus](/concepts/worker-bus). The import report carries the per-origin fleet report of that reload, so a worker a restore did not reach is named rather than hidden.

A restore that writes the `connector_connections` section also moves each restored connection's token cache entry to the restored version once the database write commits, so no worker keeps serving the pre-restore token. A connection restored with an already-lapsed session leaves no cached token behind. If that cache write fails — the connector-store Redis is unreachable — the section reports the error and the import answers `ok: false`, although the restored rows are already committed; once Redis is back, re-import the section with `"mode": "overwrite"` to rewrite the cache.

A restore that writes the `templates` section clears the compiled-template cache **fleet-wide** over the same bus and cycles the prefork pool once, so no worker — and no forked pool child — keeps serving a template compiled from the pre-restore content.

### Restore order

An import replays the selected sections in their **registration order**, never in the order
you name them: `manifest`, `env`, `access_control`, `sub_mcp`, `templates`, `states`,
`webhooks`, `conversations`, `conversation_target_config`, `schedules`,
`connector_categories`, `connector_connections`, `versioned_documents`, `tool_meta`, then the
sections plugins register. A section that decides its records against state another section
restores replays after it: `states` replays right after `templates`, and before every section
that restores a state binding.

Inside `access_control`, the principals restore first, then the route mappings, then the API
keys. A principal the restore creates gets its archived `disabled` flag with the principal
itself, before any route or key, so a failure later in the section never leaves a principal the
archive holds disabled enabled. A principal the server already holds is skipped under both
modes and keeps its live state, whatever its archived flag. A key is re-minted onto its owner,
enabled or disabled, and follows the owner's live state: while the owner is disabled the key
is denied at every door, and while the owner is enabled it authenticates — so a key restored
onto an existing, enabled owner authenticates at once, even where the archive holds that owner
disabled.

### Restoring stored definitions

Hooks, schedules, presets, per-target conversation configs, and conversation routes restore
through the **same write service** their HTTP door runs, so a restored definition passes the
same save rules a new one does:

* A state binding is validated and its named templates are **attached** — see [saving a
  binding](/concepts/states#saving-a-binding).
* A route's target bind check runs, its jq programs compile, and a `channel` row's
  `our_identity` is stored canonical and must be unclaimed.
* A preset is judged by its **document's** rules only: its name, its `output_schema` and
  `input_schema` bodies, and its binding.

A `schedules` export holds the backend's schedules as `ScheduleRecord` rows (name, the tool
the schedule fires, arguments, cadence, enabled), the same shape on every scheduling backend,
and the backend's import answers a `ScheduleImportReport`; a report of any other shape fails
the section loudly. An archive row without a `tool` or with a backend-specific schedule
shape is refused per record.

A record that fails a rule is **refused per record** — named in `errors` with its reason and
counted in `skipped` — and the rest of the section still restores. A store or transport
failure is never a per-record refusal: it stops the section there, and the section's report
carries the failure's message with zero counts and makes `ok` false. A record the section
committed before the failure stays written although the report counts none, so once the store
is reachable import the section again — under `skip` those records count as `skipped_existing`.

Two kinds of check stay at the HTTP door and do not run on a restore, because their verdict
depends on what the running server has registered rather than on the backup itself:

* **Target existence.** A restored conversation config or route may name a target the backup
  restores later (a preset in `versioned_documents`) or a plugin registers later. The door
  still refuses a target that does not exist.
* **A preset's live-registry rules** — its base tool, agent, extension, and write-validator
  checks. A restored preset whose base cannot bind is stored as a row; when the server next
  loads its presets (a reload or a restart) it is quarantined and listed as `conflicted`, with
  the reason logged at error level.

A `versioned_documents` restore holds one connection of the skeleton database while its preset
checks read the template and states stores, so it needs **two** connections of that
database's pool at once (the default pool holds ten).

## Recovering from a bad migration

The backup document above captures **platform state** — policies, presets, and the
other registered sections. It does not capture the database **schema**, which is a
separate layer: versioned as [migration chains](/concepts/marketplace#the-migrations-contract)
and recorded, one row per applied file, in the `tai_schema_history` table. That
table is the source of truth for where each component's schema stands; read it
with `tai db status`.

Migration chains roll **forward only** — there are no down-migrations, so a
migration is never "un-applied". Recovering from a migration that went wrong is a
restore-then-re-migrate, not a rollback:

**1. Restore the datastore snapshot**

Restore Postgres to a snapshot taken before the bad migration (a managed
provider's point-in-time restore, or a `pg_dump` you captured). This brings
the schema, the data, and `tai_schema_history` back to that point together —
which is why the [upgrade flow](/self-hosted/upgrades) tells you to snapshot
before a schema-carrying upgrade.

**2. Re-migrate forward**

Point the image you mean to run at the restored database and run
`tai db migrate`. The runner reads `tai_schema_history`, sees which files the
snapshot already carries, and applies only what is still pending — bringing the
chain forward to the running image. Preview it first with `tai db migrate --plan`.

> [!NOTE]
>
> Because history and data restore as one snapshot, keep the datastore backup and
> the `tai backup export` document on the same cadence — a restored database and a
> stale platform-state document drift apart otherwise.

## See also

* [Ops notes](/self-hosted/ops#schema-migrations) — `tai db status` and the migration model.
* [Access control](/guides/access-control) — one of the sections you back up.
* [Create and version a preset](/guides/create-and-version-a-preset) — presets are a backed-up section.
* [CLI reference](/reference/cli) — the full `tai backup` surface.


# Checkpoints and retention
Source: https://docs.tai42.ai/operate/checkpoints

Where agent and flow runs keep their memory, how long it lives, and the one sweep that removes it.

Every agent run, flow run and conversation turn that remembers anything keeps it in the
**checkpoint store**: LangGraph checkpoints, one thread per conversation, run or agent session.
The store is chosen once per deployment:

| Variable | Default | Effect |
| - | - | - |
| `LLM_PROVIDER_CHECKPOINT` | `redis` | The store: `redis`, `postgres`, `sqlite` (development), `memory` (development), or the name of a store a plugin registers (see [Register a checkpoint store](#register-a-checkpoint-store)). |
| `LLM_PROVIDER_CHECKPOINT_CONN_STRING` | unset | Its connection string; unset uses the store's default connection: the shared Redis URL (`redis`) or the base Postgres DSN (`postgres`). `sqlite` needs a path. With a conn string set, its retry and timeouts come from `LLM_PROVIDER_CHECKPOINT_*` (see [Connection timeouts and retries](/concepts/config-and-secrets#connection-timeouts-and-retries)). |

A run may name another provider for itself (an agent's `checkpoint_provider`, a flow's
`checkpoint_provider`); see [What a per-run provider means](#what-a-per-run-provider-means).

## The built-in stores

| Store | Survives a restart | How expired threads leave | Stores a channel | Large values stored once |
| - | - | - | - | - |
| `redis` | yes | the key TTL every write sets | in every checkpoint | by default |
| `postgres` | yes | the checkpoint sweep | once per version | when `LLM_PROVIDER_CHECKPOINT_SHARED_VALUES` is `true` |
| `sqlite` | no | the checkpoint sweep | in every checkpoint | by default |
| `memory` | no | the end of the process | once per version | when `LLM_PROVIDER_CHECKPOINT_SHARED_VALUES` is `true` |

The `redis` store needs a Redis with the JSON and search modules. Redis 8 ships both; a
Redis 7 needs RedisJSON and RediSearch loaded. On a plain Redis the store's setup fails with
`unknown command 'FT._LIST'`. With `LLM_PROVIDER_CHECKPOINT_CONN_STRING` unset, the store uses the
shared `TAI_DEFAULT_REDIS_URL`, so that Redis is the one that must provide the modules. See
[Infrastructure by feature](/operate/infrastructure) for what every store needs.

Only a store that survives a restart (`redis`, `postgres`, or a registered store that declares it)
can hold a **parked** run (one waiting on an async `ask`): a paused run must be readable by
whichever worker later resumes it.

## Retention: two horizons

| Variable | Default | Effect |
| - | - | - |
| `LLM_PROVIDER_CHECKPOINT_RETENTION_WAITING_MINUTES` | `10080` (7 days) | How long a thread its owner may still continue lives after its last write. |
| `LLM_PROVIDER_CHECKPOINT_RETENTION_FINISHED_MINUTES` | `1440` (1 day) | How long a thread its owner marked finished lives after the mark. Must not exceed the waiting value. |
| `LLM_PROVIDER_CHECKPOINT_INLINE_COMPRESS_BYTES` | `65536` | A checkpoint value whose encoding is larger is stored compressed; `null` turns compression off. |
| `LLM_PROVIDER_CHECKPOINT_SHARED_VALUES` | unset | Whether large values are stored once per thread. Unset: on for a store that copies channel values into every checkpoint, off for one that stores a channel once per version; `true` or `false` sets it for every store this deployment opens. |
| `LLM_PROVIDER_CHECKPOINT_SHARED_VALUE_BYTES` | `65536` | Where large values are stored once, a sub-value whose encoding is larger is stored once per thread and referenced. See [Large values are stored once](#large-values-are-stored-once). |

A **waiting** thread is one its owner may still continue: a parked run, an open conversation,
any thread nobody marked finished. A **finished** thread is one its owner marked finished.

* On `redis` every key a write stores carries the waiting retention as its TTL. A read never
  extends it, so a thread lives the waiting retention after its **last write**. A parked run's
  last write is its park checkpoint.
* On a store the sweep keeps (`postgres`, `sqlite`) the checkpoint sweep deletes a thread whose
  newest checkpoint is older than the waiting retention.
* A finished thread goes the finished retention after its mark, on every provider, through
  the checkpoint sweep. The mark records the time the thread becomes due, from the retention in
  force at the mark: changing the finished value later moves only new marks.

The platform may still deliver an ask's answer or expiry up to its redelivery horizon
(`INTERACTIONS_IDLE_TTL_SECONDS`, default 1 day) after the ask's deadline, so an async `ask` of
an agent run or a flow run must carry a deadline at least that long before the checkpoint's
waiting retention runs out (with the defaults, within 6 days): a park with no deadline, or one
past that point, is refused loudly before anything is parked. A resume that finds the thread's
checkpoint gone ends the run as a failed terminal.

## A thread's own retention

The two values above are every thread's **default** and its **ceiling**. A thread's owner may
declare a shorter retention for the threads it starts — a flow declares one in its document
(`config.checkpoint_retention`, see [the flows engine](/babelfish/index)) — never a longer one:

* A declared value above the platform's value for its horizon is refused loudly, naming both
  values; it is never shortened silently. A declared finished retention longer than the
  declared waiting one is refused too.
* A declaration may give only one value. An unset waiting is the platform's; an unset finished
  is the platform's finished retention, capped at the thread's waiting one.
* On `redis` the declared waiting is the TTL of every key the thread's writes store. On
  `postgres` and `sqlite` it is recorded when a run starts on the thread, and the checkpoint
  sweep reads it as that thread's waiting horizon; a later run on the same thread replaces it.
* A finished thread is due its declared finished retention after its mark.
* A park on such a thread must fit its declared waiting retention: an async `ask` whose
  deadline runs past it is refused before anything is parked.

> [!NOTE]
>
> `LLM_PROVIDER_CHECKPOINT_TTL_MINUTES` is gone: its place is taken by the two retention values
> above. The flows engine's `FLOW_CHECKPOINT_RETENTION_DAYS` and its
> `POST /api/babelfish/checkpoints/prune` route are gone too: the same two values and the
> platform's `sweep_checkpoints` operation replace them. A deployment that still sets one of
> the removed variables is refused at boot and on every settings write, naming it.

## Who marks a thread finished

The code that minted a thread id owns the thread and marks it finished at its end; every
consumer that **starts** a run on a thread takes it out of the finished set first, so a thread
used again never sits there while it is live.

* **A flow run** marks its own session thread (in its checkpoint provider's ledger) and every
  agent session thread it owns — a node whose `session_thread` template contains
  `{flow_run_id}` — finished at its terminal: success, error, stop or abort, never at a pause.
  It takes all of them out of the finished set when a run (fresh, restart, resume or step)
  starts on the session. The owned session threads are marked in the **deployment's** ledger
  (the configured provider and connection): the flow cannot know which provider each agent run
  on such a thread used.
* **An agent run** with no `thread_id` mints its thread and marks it finished when it ends
  without a park, in its own checkpoint provider's ledger. A caller-supplied `thread_id` is the
  caller's: the run takes it out of the finished set when it starts and never marks it. A run
  that parks leaves its thread to the waiting horizon.
* **A conversation** has no finished moment: a thread stays open for its next turn, so it
  leaves on the waiting horizon, or at once when an operator deletes it
  (`tai conversations delete-thread`). A turn's agent receives the conversation's thread as a
  caller-supplied `thread_id`: an agent that checkpoints on it takes it out of the finished set
  when its run starts (the agent-run rule above); an agent that keeps no checkpoints touches no
  checkpoint store.

## The checkpoint sweep

`sweep_checkpoints` (`POST /api/checkpoints/sweep`, `tai checkpoints sweep`) is the one
operation that deletes checkpoint threads. It is admin-only and destructive; drive it on a
cadence with a schedule or external cron — nothing runs it in the background.

1. Every thread marked finished whose due time has passed (its finished retention after the
   mark) is deleted, on every provider, `memory` included.
2. On a store the sweep keeps (`postgres`, `sqlite`), every thread whose newest checkpoint is older
   than its waiting retention (the one its owner declared, else the platform's) is deleted. On a
   store kept by key TTL (`redis`) the TTL does this; on an in-process store (`memory`) the thread
   lives with the process — both reported in `skipped`.

Before any delete, every **live-thread filter** a consumer registered is asked whether the
thread is still live; a thread one claims is **spared**: logged at WARNING, counted on
`tai42_checkpoint_sweep_spared_total{horizon,owner}` (served on `GET /metrics`), listed in the
result, and — for a finished thread — kept in the finished set so the next sweep checks it
again. The shipped filters claim:

| Owner | Claims a thread that |
| - | - |
| `interactions` | backs a live async park in the interactions store. |
| `agents` | has a live park barrier in the agents park index. |
| `flows-engine` | has a pending interrupt on its latest checkpoint (a parked flow session). |

A filter that fails fails the sweep. Deleting a thread removes every checkpoint and pending
write it holds, however many. A checkpoint a run writes while the thread is being deleted is
deleted again, up to 100 rounds, and then fails the sweep loudly. On the Redis provider one
delete already repeats until the thread is empty, and fails the sweep sooner: at the first
round, counting from its second, that leaves the thread holding no fewer checkpoints and writes
than the round before (`CheckpointDeleteError`, naming the thread and what it still holds).

The result:

| Field | Meaning |
| - | - |
| `provider` | The deployment's checkpoint store. |
| `waiting_minutes`, `finished_minutes` | The platform's two retention values: the default and the ceiling of every thread's retention. |
| `swept_count` | Threads deleted in this sweep. |
| `finished_swept` | Threads deleted past the finished horizon. |
| `waiting_swept` | Threads deleted past the waiting horizon. |
| `spared` | Threads past a horizon a live-thread filter reported live. |
| `skipped` | Why the waiting horizon was not swept (a store kept by key TTL or by its process), else `null`. |

### Scope: the deployment's store

The sweep covers the configured provider and connection string only — the one store every
process shares.

### What a per-run provider means

* A thread on a per-run `redis` store leaves on its key TTL (the waiting retention), marked or
  not.
* A thread on a per-run `memory` store lives with its process.
* A thread on a per-run `postgres` or `sqlite` store is not swept; its marks land in that
  store's own ledger, so a deployment whose configured provider is that store sweeps them.
* A flow-owned session thread whose agent ran on a per-run provider is marked in the
  deployment's ledger; the sweep's delete there finds nothing, and the thread leaves on its
  own store's waiting horizon.

## The store format

The kit records a **format generation** in each store the first time a saver is built on it (an
in-process store starts empty with its process and needs none). A store that already holds checkpoints written in another
format — or with no recorded generation — is refused at that first use with
`CheckpointStoreFormatError` ("reset the checkpoint store before starting this version"): every
run, query or sweep that needs it fails loudly until the store is reset. A deployment that
uses no checkpoint store never builds a saver and never runs the check. The current generation
is 4: a store written by an earlier version is reset before this one starts on it. Drain in-flight
runs before the upgrade: the reset removes every open conversation's memory, every parked run and
every flow session the store held.

## Large values are stored once

A run's state often carries the same large value in many checkpoints: a document that stays the
same while others change, or a result every later step keeps. Where storing once is on, a value
whose encoding is larger than `LLM_PROVIDER_CHECKPOINT_SHARED_VALUE_BYTES` is stored **once per
thread**, keyed by the SHA-256 of its encoding, and every checkpoint and pending write that
carries it holds a small reference in its place. The rule works on a value at any depth: a
dictionary of documents keeps each large document as its own stored value, so changing one
document stores only that one again. A value larger than `LLM_PROVIDER_CHECKPOINT_INLINE_COMPRESS_BYTES`
is stored compressed.

A store that copies channel values into every checkpoint stores large values once by default; one
that stores a channel once per version does not. So it is on for `redis` and `sqlite` by default:
their savers write every channel into every checkpoint, so a large value is otherwise copied into
each one. It is off for `postgres` and `memory` by default: their savers already store a channel
once per version, so storing sub-values once there saves bytes only inside a changing channel (on
`postgres`, in measured conversations the stored bytes fell to between about half and five sixths)
at a small cost on every save and read (about 2 ms per save in the same measurement). A deployment
turns it on or off for every store it opens with `LLM_PROVIDER_CHECKPOINT_SHARED_VALUES`.

* On `redis` each stored value is a key `tai42:checkpoint:value:{<thread>}:<digest>`, and a set
  `tai42:checkpoint:values:{<thread>}` lists the thread's values. Every write that references a
  value stamps it with the waiting retention, so a value lives as long as the newest checkpoint
  that references it.
* On `postgres` the values are rows of the table `tai42_checkpoint_values`, next to the saver's
  own tables; on `sqlite` they are rows of a table of the same name in the store's file; on
  `memory` they live with the process, like its checkpoints.
* A value leaves with its thread: deleting a thread (the checkpoint sweep, `tai conversations
  delete-thread`, a flow restart) deletes its values after its checkpoints, and on `redis` a
  thread nobody writes to again expires with its keys.
* Reading a checkpoint fetches all its referenced values, the values nested inside them included, in
  one extra round trip; every place that holds a value receives its own copy. A reference whose
  value the store no longer holds fails the read with `CheckpointReferenceError`, naming the
  thread and the value: that thread cannot be read; delete it.
* On `postgres` a value is written just before the checkpoint that references it. A process that
  stops between the two leaves that value's row until its thread is deleted; for a thread whose
  first checkpoint never landed, the sweep never sees the thread, so the row stays until that
  thread id is deleted (`tai conversations delete-thread`). The library's own blob rows have the
  same limit when a process stops in the middle of a thread's delete.
* The switch decides what a write stores. A checkpoint written while values were stored once
  reads back with its values whatever the switch says now; with the switch off a save and a read
  cost nothing beyond the saver's own work.

## Register a checkpoint store

A checkpoint store is a **registration**: a subclass of `CheckpointProvider`
(`tai42_kit.llm.checkpoint`) that names the store, states three facts about it, and provides the
hooks the platform applies its features through. The four built-in stores are registrations of
the same kind; any saver written to LangGraph's `BaseCheckpointSaver` contract can be one.

The name is the value of `LLM_PROVIDER_CHECKPOINT` (and of a run's own `checkpoint_provider`):
lowercase letters, digits, `_` and `-`, starting with a letter. The facts
(`CheckpointProviderFacts`) and what each makes the platform do:

| Fact | Values | What the platform does with it |
| - | - | - |
| `durable` | `true`, `false` | A durable store can hold a parked run. A store whose threads end with its process cannot be durable. |
| `retention` | `native_ttl`, `sweep`, `process` | How expired threads leave: the TTL the store's own keys carry (a thread's declared waiting gets a saver of its own), the checkpoint sweep through the store's ledger, or the end of the process. |
| `channel_storage` | `per_checkpoint`, `per_version` | How the saver stores a channel value: copied into every checkpoint, or once per version. A `per_checkpoint` store stores large values once by default; a `per_version` store does not. |

What a registration provides:

* `open(conn_string)`: opens the store and returns its resource — the handle the saver is built
  on, the store's finished-thread ledger and its per-thread value store — and the function that
  closes it. A store with no default connection raises naming the setting when `conn_string` is unset.
* `saver(resource)`: the store's saver, as its library builds it.
* `value_encoding(saver, compress_threshold)`: how the store encodes a value for its value store
  and the resolver (`MsgpackValueEncoding` fits any saver that encodes values with its
  serializer's msgpack form).
* `recorded_generation`, `record_generation`, `holds_checkpoints`: the store-format marker and
  whether the store holds checkpoints, for the [format check](#the-store-format).
* `saver_with_waiting(resource, waiting_minutes)`, required when `retention` is `native_ttl`: a
  saver and a value store whose writes carry that waiting as their key TTL.
* Optionally `serializer(saver, compress_threshold)`, the serializer and codec the platform
  installs on the saver, and `prepare_checkpoint` / `prepare_writes`, a write preparation that
  knows the store's own saver (the default follows `channel_storage`). The codec writes every
  value the saver stores, a value the platform encodes ahead of the saver included, and reads
  each one back.

What the platform does for every store alike: the serialization guard on the saver, large values
stored once per thread with every read resolving them, the format check at first use, the
retention views and the checkpoint sweep through the store's ledger. The kit's ledgers, value
stores and encodings for Redis, Postgres, sqlite and in-process stores are reusable by a
registration on the same kind of connection (`tai42_kit.llm.checkpoint.stores`).

To register a store, its module calls `register_checkpoint_provider` at import (or decorates the
class with it); a deployment lists that module under the manifest's `lifecycle_modules` and sets
`LLM_PROVIDER_CHECKPOINT` to the store's name:

```python theme={null}
from tai42_kit.llm.checkpoint import CheckpointProvider, CheckpointProviderFacts, register_checkpoint_provider


@register_checkpoint_provider
class AcmeCheckpointStore(CheckpointProvider):
    name = "acme"
    facts = CheckpointProviderFacts(durable=True, retention="sweep", channel_storage="per_version")
    ...  # the hooks above
```

The seam's names, their signatures and their docstrings are in the
[checkpoint stores reference](/reference/python-sdk/kit-checkpoint).

Every mistake is refused loudly: a store name no module registered fails the store's first use,
naming the registered stores; registering another class under a name already held, a malformed
name, facts outside their values, a durable store whose threads end with its process, a
`native_ttl` store without `saver_with_waiting`, or a class missing a hook is refused at import,
naming it. Registering the same class again (a module re-imported by a reload) changes nothing.

## What the Redis store keeps

JSON has no form for most Python values a run's state holds, so the Redis codec stores each
such value in a typed envelope and reads it back as the same type: `datetime`, `date`, `time`,
`timedelta`, `timezone` (a `datetime.timezone`, or the fixed offset pydantic attaches to a value it
parses from text, bare or on a value), `zoneinfo.ZoneInfo`, `Decimal`, `UUID`, tuples, sets and frozensets,
dictionaries with non-string keys, bytes nested inside a value, enum members, pydantic models
and dataclasses (their classes importable by module path), the LangChain objects LangChain's
own loader revives (its messages, documents and prompts) and LangGraph's own types. A value of
any other type is refused at write, naming its path: so is a `NaN` or infinite float, which
JSON cannot hold, and a LangChain object its loader will not revive, such as a subclass of a
message class. A stored envelope that cannot be read back fails the read.

A `datetime` or `time` keeps its wall-clock value, its `fold` and its `tzinfo` when that is a
fixed offset (`datetime.timezone`, its name kept; the fixed offset pydantic attaches to a value
it parses from text is read back as a `datetime.timezone` with the same offset and name) or an
IANA zone (`zoneinfo.ZoneInfo`, kept by its key), so a value read back still follows its zone's
daylight-saving rules. One carrying any other kind of `tzinfo`, or a zone read from a file
(which has no key), is refused at write, naming its path; a stored zone key the reading host's
zone database lacks fails the read.

An **exception** is stored as a readable record and comes back as a `CheckpointedException`
carrying it:

```json theme={null}
{
  "id": ["myapp", "errors", "StepFailed"],
  "message": "step fetch failed",
  "kwargs": {"step": "fetch", "attempts": 3},
  "repr_kwargs": [],
  "cause": {
    "id": ["builtins", "TimeoutError"],
    "message": "upstream timed out",
    "kwargs": {},
    "repr_kwargs": [],
    "cause": null
  }
}
```

`kwargs` holds the exception's attributes; an attribute JSON cannot hold is stored as its
`repr()` and named in `repr_kwargs`, and an attribute holding another exception becomes its own record.
`cause` is the record of the exception it was raised from.


# Deploy
Source: https://docs.tai42.ai/operate/deploy

Run a server for real.

Run a server for real — transport selection, environment, and the config-provider swap point.

A production server is `tai serve` with a transport, a bound address, a manifest, and the environment its tools need. This page covers those choices. Provider-specific settings (a config provider's own environment variables) live in that provider's repository README.

> [!NOTE]
>
> Running inside your own ASGI process instead of `tai serve` — a plain uvicorn run or a mount in an existing FastAPI/Starlette app? See [Embed in your own ASGI process](/operate/embed).

## Choose a transport

`tai serve` runs the MCP server over one transport. Select it with `-t/--transport`:

| Transport | Use it for |
| - | - |
| `stdio` | a local client that launches the server as a subprocess |
| `http` / `streamable-http` | a network endpoint; stateful by default |
| `sse` | a network endpoint over server-sent events |

```bash theme={null}
tai serve --transport http --host 0.0.0.0 --port 8000
```

For a fast same-machine path, bind a Unix domain socket with `--uds /path/to/socket` instead of a host and port.

## Scale workers

Run multiple worker processes with `-w/--workers`. The transport constrains the worker count:

* `stdio` and `sse` run a single worker.
* `http` / `streamable-http` run a single stateful worker by default; pass `--stateless-http` to lift the single-worker restriction and run several.

More than one worker also **requires the [worker bus](/concepts/worker-bus)** and shared sub-MCP and hooks stores: set `TAI_BUS_REDIS_URL`, `SUB_MCP_REDIS_URL` and `HOOKS_REDIS_URL` (`TAI_DEFAULT_REDIS_URL` stands in for all three). Without the bus, sibling workers would serve stale config after a reload with no channel to converge on. Without a shared Redis, each store is per-process: a sub-MCP app registered on one worker is not served by its siblings, and a hook registered on one worker never runs for an event another worker accepts.

```bash theme={null}
export TAI_BUS_REDIS_URL="redis://localhost:6379/0"
export SUB_MCP_REDIS_URL="redis://localhost:6379/0"
export HOOKS_REDIS_URL="redis://localhost:6379/0"
tai serve --transport streamable-http --workers 4 --stateless-http
```

The full worker and transport option surface:

```bash examples/deploy/serve_workers_help.sh theme={null}
# Run multiple worker processes with -w/--workers. Stateful HTTP transports refuse
# more than one worker; --stateless-http lifts that restriction for http /
# streamable-http. More than one worker also REQUIRES the worker bus — set
# TAI_BUS_REDIS_URL, or sibling workers would serve stale config after a reload
# with no channel to converge on — and the shared SUB_MCP_REDIS_URL and
# HOOKS_REDIS_URL stores (TAI_DEFAULT_REDIS_URL stands in for all three), so sub-MCP
# registrations and hooks are shared across workers. Each worker checks them at its
# boot, after the stored env is applied, and tai serve exits non-zero on a refusal.
tai serve --help
```

> [!WARNING]
>
> `--workers > 1` is refused for `stdio` and `sse`, and for `http` / `streamable-http` unless `--stateless-http` is set. A stateful HTTP server keeps session state a second worker would not see.
>
> `tai serve` hands its worker count to each worker, and each worker refuses to boot without the bus or with either store in-memory, naming the setting to set. The worker checks after it applies the stored env (the config-dir `.env` or the config provider's store), so a URL kept only in the stored env counts, and a stored empty value over a value set in the container is refused. A worker that refuses fails its startup, and `tai serve` exits non-zero. A config reload, and any config write (an env change, a manifest change, a profile replace), that would leave a multi-worker server without the bus or with either store in-memory is refused the same way.

> [!NOTE]
>
> A single-worker deployment may run on the default in-memory stores, unless it registers an [execution backend](/operate/backends): a `backend_module` needs the shared hooks store at any worker count, because the backend process matches the events it raises against its own hooks registry, and an in-memory one holds none of the hooks registered through the server.

### When a worker dies

The serve process checks each worker on a health ping and replaces any worker that dies. Each replacement logs one `WARNING` on the `uvicorn.error` logger. It gives the worker's pid, why it died, and its exit code or the signal that ended it:

| Line | What happened |
| - | - |
| `Child process [N] died (exited by itself): killed by signal SIGSEGV (-11)` | The worker ended on its own. The status is its own: a crash signal (`SIGSEGV`, `SIGABRT`), `SIGKILL` from outside the server (for example the kernel's out-of-memory killer), or `exit code N`. |
| `Child process [N] died (did not answer the health check within 5s and was killed): killed by signal SIGKILL (-9)` | The worker was alive but did not answer the ping in time, so the server killed it. The limit is uvicorn's health-check timeout, 5 seconds by default; pass `--timeout-worker-healthcheck SECONDS` after the `tai serve` options to change it. |
| `Child process [N] died (crashed and was dumping core when it missed the health check, so it was killed): killed by signal SIGKILL (-9)` | The worker crashed. It was still writing its core dump when it missed the ping, so the server killed it. |

Every worker and the serve process also enable Python's fault handler. A worker that crashes in native code writes `Fatal Python error: ...` and the stack of every thread to stderr before it dies, unless `PYTHONFAULTHANDLER` already configures it.

## Point at a manifest and environment

The server loads a manifest and reads its environment at startup. Point at the manifest with `--manifest-path`, or set `TAI_MANIFEST_PATH` as the flag's default. Provide the environment your tools need — see the repository's `.env.example`.

```bash theme={null}
export TAI_MANIFEST_PATH="$(pwd)/manifest.yml"
tai serve --transport http
```

The default config directory the `file` provider anchors `.env`, `manifest.yml`, and templates under is `/app`; override it with `TAI_CONFIG_DIR_PATH`.

## HTTP routers and headless mode

Out of the box the server serves the **full Studio surface** — every built-in page and its API — with no router list in the manifest. The `default_routers` field controls this:

* **`all`** (the default) — serve the whole Studio UI plus its API. A bare manifest gives you the full surface; you never enumerate the core routers, and no page is left dark for want of a listing.
* **`api`** — a **headless** deployment: mount the core JSON API (`/api/*`) but do not serve the browser SPA. Use it for an API-only backend with no UI.
* **`none`** — mount nothing by default and list every router in `routers_modules` yourself. For a fully manual or MCP-only surface.

Feature lifecycles do not follow the router selection: the conversations completion tools, re-drive and delivery sweep run under every value, and the marketplace advisory poll starts only where `GET /api/marketplace/advisories` is served (under `none`, list `tai42_skeleton.routers.marketplace` to serve it).

`routers_modules` adds extras — your own routers, a plugin's — on top of the selected set; the loader keeps the Studio SPA catch-all last. See [the manifest](/concepts/manifest#http-routers) for the field reference.

## Run mode and logging

`TAI_RUN_MODE` selects how `tai serve` runs. Leave it unset (or empty) for the normal multi-worker server; set it to `debug` for a single in-process server, which ignores `--workers`. Any other value is **rejected loudly** at startup rather than silently falling through — a typo never selects a mode.

```bash theme={null}
export TAI_RUN_MODE=debug   # single in-process server; --workers is ignored
tai serve --transport http
```

Set the log level with `TAI_LOG_LEVEL` (default `INFO`). A config reload that changes it re-applies logging under `tai serve`.

```bash theme={null}
export TAI_LOG_LEVEL=DEBUG
tai serve --transport http
```

See [Config and secrets](/concepts/config-and-secrets#settings-reference) for the full environment-variable reference, including the timeout and limit knobs.

## Swap the config provider

Where the server reads its env and manifest is a swappable provider. The default `file` provider reads from disk with zero dependencies. Select a different provider — for example a Kubernetes-backed one — with `TAI_CONFIG_MODE`:

```bash theme={null}
export TAI_CONFIG_MODE=kubernetes   # requires the kubernetes config provider plugin installed
```

A config provider is a plugin; its own settings live in its repository README. See [Config and secrets](/concepts/config-and-secrets).

> [!WARNING]
>
> `TAI_CONFIG_MODE=kubernetes` **requires the [worker bus](/concepts/worker-bus)**. The `kubernetes` config mode exists for multi-pod shared config, and a pod cannot see its own replica count, so a busless `kubernetes` boot is refused — set `TAI_BUS_REDIS_URL`. The refusal names the missing bus, not a later kubeconfig error.

## Access control at deploy

Enabling access control (`ACCESS_CONTROL_ENABLE`, on by default) adds three deploy requirements.

**Postgres for the policy store.** The access-control policy and route tables live in the [named database](/concepts/config-and-secrets#named-databases) the core `skeleton` component binds to — the `default` database unless `TAI_DB_BINDING_SKELETON` points it elsewhere. Configure that database, including its password:

```bash theme={null}
export TAI_DATABASE_DEFAULT_PG_HOST=postgres.internal
export TAI_DATABASE_DEFAULT_PG_DB=tai
export TAI_DATABASE_DEFAULT_PG_PASSWORD="$PGPASSWORD"
```

**Any plain Redis.** The auth gate reads its live context from plain Redis hashes. There is no baked-in default: point the connection with `ACCESS_CONTROL_REDIS_URL`, or let it resolve from the shared `TAI_DEFAULT_REDIS_URL` — with the gate on, one of the two must be set, or every request that carries a key is denied. The Redis API-key provider keeps its records in its own Redis, `TAI_IDENTITY_REDIS_URL`, which also falls back to `TAI_DEFAULT_REDIS_URL`. Any standard, module-less `redis-server` — `redis:7`, `redis:8`, or `valkey` — runs access control, the worker bus, the task backends, and the feature stores. The one exception is the default checkpoint store and LLM store (`LLM_PROVIDER_CHECKPOINT` and `LLM_PROVIDER_STORE` set to `redis`): they need a Redis with the JSON and search modules — Redis 8, or a Redis 7 with RedisJSON and RediSearch loaded. See [Checkpoints](/operate/checkpoints) and [Infrastructure by feature](/operate/infrastructure).

**An identity provider in the manifest.** The skeleton ships no concrete identity provider, so a deployment with access control enabled **must** name one as a `lifecycle_modules` entry — its module registers the provider at import. The usual choice is the Redis-backed api-key provider, which registers itself as the `"redis"` provider. `ACCESS_CONTROL_AUTH_PROVIDERS` — an ordered JSON list — names the chain the verifier tries; unset, the chain is every registered identity provider, sorted by name. Swap the module to change the authn backend.

```yaml examples/deploy/access_control_manifest.yaml theme={null}
# A deployment-shaped manifest. Entries are Python import paths — naming a module
# here imports it at boot so its registration decorators run.
#
# `lifecycle_modules` carries the identity provider. The skeleton ships NO concrete
# provider, so a deployment with access control enabled MUST name one. This default
# registers itself as the "redis" identity provider at import; ACCESS_CONTROL_AUTH_PROVIDERS
# (an ordered JSON list, default ["redis"]) names the chain the verifier tries. Swap this line to change the authn backend.
lifecycle_modules:
  - tai42_identity_redis.redis_api_key_provider
# A durable store backend for tools/config and a task backend for background,
# scheduled, and distributed runs. A registered backend requires the worker bus
# (the backend-runtime and server processes converge on reloads through it) and a
# shared hooks registry (the backend runtime matches the events it raises against
# its own registry), so set TAI_BUS_REDIS_URL and HOOKS_REDIS_URL (env vars, not
# manifest keys; placeholder host):
#
#   TAI_BUS_REDIS_URL=redis://redis.internal:6379/0
#   HOOKS_REDIS_URL=redis://redis.internal:6379/0
storage_module: tai42_storage_local
backend_module: tai42_backend_arq
# The core API routers and the Studio SPA mount by default (`default_routers`
# defaults to `all`), so a UI-driven server needs no router list here — add only
# extras or plugin routers under `routers_modules`.
```

**Serving the Studio needs no SPA public prefixes.** With access control on, you do **not** pin `/`, `/assets`, `/vendor`, or any SPA path public — the [dataless Studio SPA shell](/concepts/access-control#the-studio-spa-shell-is-public-its-data-is-not) is served on any unmatched non-`/api` GET by default (`spa_shell_public`), and it leaks nothing because all data sits behind authenticated `/api/*` calls. The login routes under `/api/login` are public by their own route declaration, and everything else under `/api/*` stays authed. A headless (no-Studio) deployment can set `spa_shell_public` to `false` to turn the fallback off.

**No route-to-scope step is needed to make the deployment usable.** The seeded roles (admin/editor/viewer) carry the universal scope, so on a fresh deployment every role-holder reaches every registered `/api` route — including the MCP transports — out of the box, with the route table empty. `tai scopes add` is only for **scoped keys**: map a route to a named scope to let a key minted with that scope (rather than `*`) reach it.

See the [access-control guide](/guides/access-control) for the end-to-end walkthrough.

## Liveness and readiness

The server exposes two operational routes for orchestrators and load balancers. Both are `GET`, unauthenticated, and served outside the OpenAPI surface — there is no CLI command for them.

| Route | Probes | Response |
| - | - | - |
| `/health` | nothing — pure liveness | `200 OK` |
| `/ready` | every backing store this deployment has wired (Redis/Postgres), each pinged once under a 5s budget | `200` `{"status":"ready", ...}` when all pass; `503` `{"status":"not_ready", ...}` if any fails |

`/health` stays green as long as the process is up. `/ready` lets an orchestrator hold traffic off a worker whose Redis or Postgres is unreachable — such a worker would 500 every real request but stay live.

Each subsystem declares the stores it uses, and `checks` carries one row per name its targets declare. A row appears only when its store is configured. The platform's own subsystems name their rows after themselves:

| Row | Store pinged |
| - | - |
| `access_control` | the access-control gate's own Redis (`ACCESS_CONTROL_REDIS_URL`), whenever access control is enabled |
| `tool_runs` | the background tool-runs Redis |
| `interactions` | the interactions Redis |
| `rate_limit` | the rate-limit counter Redis, while any door family is enabled |
| `hooks` | the hooks Redis, unless hooks run in memory |
| `sub_mcp` | the sub-MCP registration Redis, unless it runs in memory |
| `connectors` | the skeleton database, plus the connector-store Redis cache when one is set |
| `versioning`, `marketplace`, `tool_meta` | the skeleton database |
| `states` | the state store's bound database (`TAI_DB_BINDING_STATES`; the skeleton database unless bound elsewhere) |
| `conversations` | the conversation-bridge Redis (`CONVERSATIONS_REDIS_URL`) |
| `bus` | the worker-bus Redis (`TAI_BUS_REDIS_URL`) |

Each enabled identity provider adds the stores it declares for itself, under the row names it chooses: the [accounts provider](/plugins/tai42/accounts-postgres) reports its Postgres and its Redis as `accounts`, and the [Redis API-key provider](/plugins/tai42/identity-redis) reports its record store as `access_control`. Key a readiness gate or alert on the row names your deployment's `/ready` returns.

Rows that share one connection are pinged once and report that one result. A dead conversation-bridge or worker-bus Redis fails readiness like any other wired store.

**A stalled background task fails readiness.** Beyond the backing-store pings, `/ready` also reports the platform's own long-lived background tasks — the fleet-bus subscription, the failed-MCP re-probe, and the expiry reapers. If one of these stops unexpectedly, `/ready` returns `503` `not_ready` and names the stopped task under `checks` (as `perpetual_task:<name>`), and the process exits so a supervisor that restarts it (`restart: unless-stopped` in the bundled Compose, or an equivalent orchestrator policy) brings it back from a clean boot. `/health` keeps returning `200` until the process actually exits, so a liveness probe alone will not notice the stall — wire the restart policy, and probe `/ready` where your orchestrator supports a readiness gate.

**The probe routes are public by default — no manual step.** With access control enabled, unknown routes are denied, but `/health` and `/ready` are served public by the app's own route-level declaration: they ship in `ACCESS_CONTROL_ACKNOWLEDGED_PUBLIC_ROUTES`, so a probe carrying no key reaches them with nothing to configure. Do **not** also list them in `ACCESS_CONTROL_ALWAYS_PUBLIC_PATH_PREFIXES` — an acknowledged route that overlaps an always-public prefix is rejected at boot.

> [!NOTE]
>
> `/ready` passes the access-control gate without reading the gate's own Redis, because the route is declared public. A dead gate Redis therefore reaches the handler and fails the `access_control` row, so the probe returns `503` while every request to a protected route is refused.

## Preflight check

Run read-only health diagnostics before serving — Python version, config mode, the `skeleton` database (reached with the migrator identity), whether its schema is applied, and the connector-store Redis (`CONNECTOR_STORE_REDIS_URL` or `TAI_DEFAULT_REDIS_URL`). An unconfigured database or Redis counts as a failed check. It exits non-zero when any check fails, and redacts credentials. It does not check the other Redis features; [Infrastructure by feature](/operate/infrastructure) lists them.

```bash theme={null}
tai doctor
```

> [!NOTE]
>
> Requires Python 3.13+. `tai` ships with the runtime — `pip install tai42-skeleton`. To run it against an unreleased change instead, install from the repository: `pip install git+https://github.com/tai42ai/tai42#subdirectory=core/skeleton`.

## Self-host the whole stack

Running the platform as containers — the minimal-core image, Postgres and
Redis, and the Compose bundle — is covered in
[Operate](/operate). Datastores are never host-published there; only serve's
port is, and access control gates it exactly as above.

## See also

* [Transports](/concepts/transports) — the HTTP, SSE, stdio, and UDS paths in depth.
* [Config and secrets](/concepts/config-and-secrets) — the config-provider seam.
* [Infrastructure by feature](/operate/infrastructure) — which feature needs Postgres, Redis, or another service.
* [Integrations](/integrations) — point an MCP client at the running server.
* [CLI reference](/reference/cli) — the full `tai serve` surface.


# Embed in your own ASGI process
Source: https://docs.tai42.ai/operate/embed

Serve the runtime from a factory you own — a plain uvicorn run, or mounted inside an existing app.

Serve the runtime from an ASGI app you own, instead of the `tai serve` CLI.

`tai42_skeleton.asgi.create_app` returns the same ASGI app `tai serve` runs. You own the process, the uvicorn flags, and the hosting — run it with your own `uvicorn main:app`, or mount it inside an existing FastAPI/Starlette service.

There are two entry modes, and they trade the same way. The tai CLI is the managed path: its command family — `tai serve`, `tai backend`, `tai metrics` — owns the worker fleet, the metrics sidecar, the backend worker processes, UDS binding, and logging, a full ops surface across a few commands. The factory is the embedded path: you drop the runtime into a service you already run and keep your own process manager, uvicorn invocation, and logging story. Pick the CLI for a standalone server; pick the factory to embed the runtime in an existing process.

## Serve directly

The minimal host is a module that builds the app and a uvicorn command that serves it.

```python main.py theme={null}
from tai42_skeleton.asgi import create_app

app = create_app(manifest_path="manifest.yml")
```

```bash theme={null}
uvicorn main:app --host 0.0.0.0 --port 8000
```

The MCP endpoint stays under `/mcp`, and the Studio SPA and API routes serve exactly as they do under `tai serve` — the factory returns the same app, so nothing about the request surface changes.

## Mount inside an existing FastAPI or Starlette app

Mounting the app is not enough on its own. Starlette does **not** run a mounted sub-app's lifespan, so the runtime never boots unless the host runs the tai app's lifespan itself. The `lifespan` helper returns the tai app's lifespan context manager; compose it into the host's lifespan, then mount the app:

```python main.py theme={null}
import contextlib

from fastapi import FastAPI
from tai42_skeleton.asgi import create_app, lifespan

tai = create_app(manifest_path="manifest.yml")


@contextlib.asynccontextmanager
async def host_lifespan(app: FastAPI):
    async with lifespan(tai):
        yield


host = FastAPI(lifespan=host_lifespan)
host.mount("/tai", tai)
```

> [!WARNING]
>
> Skip the composed lifespan and the runtime never boots. Every request to the mounted app answers `503 Service Unavailable` with `Initializing...`, and the `tai42_app` handle raises `AttributeError: ... before bind()` in any plugin code that touches it at import. The mount succeeds; the app just never starts.

## One app per process

The `tai42_app` handle is a process-global singleton, and so is the built app. A second `create_app` lifespan entered **while another is still active** in the same process raises `RuntimeError` rather than silently rebinding the handle. Sequential lifespans in one process — enter, exit, then enter again — stay legal. Two different apps means two processes.

## Multi-worker and fleet sync

Run several workers with `uvicorn main:app --workers 4`, and the HTTP transports need `create_app(..., stateless_http=True)` — the same session-pinning rule the CLI enforces, because a stateful session is pinned to the worker that created it and a second worker would not see it. The factory cannot see your worker count, so this matrix is yours to get right. See [Transports](/concepts/transports) for the statefulness and worker rules in full.

> [!WARNING]
>
> **The worker bus and the shared stores are yours to enable when you embed.** The [workers boot rules](/concepts/worker-bus#boot-rules) count the workers `tai serve` hands each worker; an external process manager driving the factory with its own `--workers` hands no count, and in-process code cannot count sibling processes, so each embedded process counts as one worker and those rules never refuse. So a `uvicorn main:app --workers 4` embed boots yet runs busless-stale unless you set `TAI_BUS_REDIS_URL` yourself. Set it in any multi-process embed. The same holds for the sub-MCP and hooks stores: set `SUB_MCP_REDIS_URL` and `HOOKS_REDIS_URL` (or `TAI_DEFAULT_REDIS_URL`) yourself, or a sub-MCP app or hook registered through one worker is unknown to its siblings. The rules that read the manifest do run in the embedded app's lifespan: a manifest that registers a `backend_module` without `TAI_BUS_REDIS_URL`, or over an in-memory hooks registry (no `HOOKS_REDIS_URL` and no `TAI_DEFAULT_REDIS_URL`), refuses to start at any worker count.

> [!WARNING]
>
> The embedded app serves no `/metrics` route of its own, so metrics are a separate concern under `--workers N`. For correct multi-worker metrics, point every worker at a shared `PROMETHEUS_MULTIPROC_DIR` (the Prometheus multiproc opt-in described below): each worker writes its counters into that directory, and a separate reader — the `tai metrics` server, or your own reader over the same directory — aggregates them across the fleet.

Fleet convergence — a config reload reaching every worker — rides the app's own [worker bus](/concepts/worker-bus), internal infrastructure you enable with `TAI_BUS_REDIS_URL`. It is not a backend capability and not a CLI feature, so an embedded worker joins the fleet the moment the bus is configured, exactly like a `tai serve` worker. With no bus configured a mutation applies in that one process and reaches no sibling — the correct behavior only for a genuinely single-process embed.

## What the CLI owns that embedding does not

Some of what `tai serve` sets up, the factory deliberately leaves to you.

* **Root logging.** The factory configures no logging — bring your own. A tai config reload that changes `TAI_LOG_LEVEL` does **not** re-apply logging in an embedded process; that re-apply is CLI-owned.
* **Prometheus metrics.** The embedded app serves no `/metrics` route — exposing metrics is a separate concern you run yourself. Export `PROMETHEUS_MULTIPROC_DIR` before the first import; the app's workers write their counters into that directory, and a separate reader — the `tai metrics` server, or your own reader pointed at the same directory — reads and exposes them. You own that directory's lifecycle, including wiping stale files between runs.
* **The metrics sidecar, backend worker processes (`tai backend`), and UDS handling.** These are fleet-orchestration concerns the CLI owns; the factory does none of them.

The runtime still makes four process-global changes inside your process. Know them before you embed:

1. **Manifest env stamp.** When you pass `manifest_path`, the app writes `TAI_MANIFEST_PATH` into the process environment for the lifespan's duration, and restores the prior value on exit. Host code reading that variable during the tai app's life sees the tai-set value.
2. **Config env store.** On every config reload — first reload onward, since boot-time `.env` loading is a CLI-only `load_dotenv` the factory never runs — tai's config engine applies its managed `.env` store to the process environment: `os.environ` gains every key in the store and drops keys removed from it. Host code reading those keys sees tai-managed values. Keep tai env keys namespaced away from your host app's, and never put `TAI_MANIFEST_PATH` or `PROMETHEUS_MULTIPROC_DIR` in the tai env store of an embedded deployment — the factory's own lifespan stamp and the multiproc opt-in own those.
3. **Default metrics registry.** Without `PROMETHEUS_MULTIPROC_DIR`, tai's counters register into the process-wide `prometheus_client` default registry. tai exposes no `/metrics` route itself, but because that registry is shared, a host that serves its own default-registry `/metrics` includes tai's counters. This is inherent `prometheus_client` behavior; setting `PROMETHEUS_MULTIPROC_DIR` moves tai's counters into the multiproc directory and separates them.
4. **Log-record redactor.** The app installs the kit's record redaction (`tai42_kit.logging.install_record_redaction`), a `logging.setLogRecordFactory` wrapper that applies every redactor a feature registered with `tai42_kit.logging.register_record_redactor` — the connector-secret rule among them — to log records. In embed mode it applies **only to the records tai's operation feeds** — the `tai` logger family (`tai42_skeleton`, `tai42_kit`, `tai42_contract`, and the rest) plus the `mcp` / `fastmcp` library loggers the runtime drives, whose session layers are the primary token-carrying path — so an embedded tai app cannot leak connector secrets through the logs its operation produces, while your app's own records pass through untouched. Under the `tai` CLI, where tai owns the whole process, the wrapper covers every record in the process instead. It is fail-closed: a record the redactor cannot process is still emitted, but its message is replaced by an error marker and its args, exception, and stack are blanked — content is scrubbed rather than leaked.

These effects do not share a lifetime. The manifest env stamp (1) is lifespan-scoped and restored on exit — the exit restore reinstates the pre-app value even if a mid-life config reload wrote that variable, because the `manifest_path` parameter is authoritative for the lifespan. The other three persist for the **process** lifetime: after a tai lifespan exits — sequential re-init is legal — reload-applied env keys linger, registered counters remain in the default registry, and the redactor's factory wrapper stays installed, still inspecting every record the process creates and redacting the in-scope ones.

## See also

* [Deploy](/operate/deploy) — running a standalone server with `tai serve`.
* [Transports](/concepts/transports) — the statefulness and worker rules the multi-worker matrix follows.
* [Config and secrets](/concepts/config-and-secrets) — the config engine whose env store the runtime applies on reload.
* [`tai42_skeleton.asgi`](/reference/python-sdk/skeleton-asgi) — the `create_app` and `lifespan` signatures and parameters.


# Operate
Source: https://docs.tai42.ai/operate/index

Self-host the platform from the distribution bundle, then run it: deploy, observe, back up, and wire the plugins an install needs.

Everything an operator does after the runtime works on a laptop: self-host it
from the distribution bundle, run and observe it, and wire the shipped plugins
an install needs.

> **[Deploy](/operate/deploy)**
>
> Run a server for real.

> **[Infrastructure by feature](/operate/infrastructure)**
>
> Which features need Postgres, Redis or another service.

> **[Observe](/operate/observe)**
>
> Collect metrics and traces.

> **[Manage a fleet](/operate/manage-a-fleet)**
>
> Read the worker census and drive fleet-wide operations.

> **[Plugin setup](/operate/backends)**
>
> Backends, storage, accounts, identity, and monitoring.

## Self-host with the distribution bundle

[`tai-distribution`](https://github.com/tai42ai/tai-distribution) packages the
whole platform as one minimal-core container image plus a Docker Compose
bundle. The image ships the platform core, the agents layer, and the baked
reference providers — local storage, the arq backend, redis identity, and both
sandbox providers — and bakes the built [Studio](/studio) in,
so a self-hosted install is one image and the services it talks to. Every other
plugin (the channels, the S3/GitHub storages, the celery/rq backends, the
connectors, monitoring, accounts, and the extra tools) installs at runtime
through the [marketplace](/concepts/marketplace) or bakes into a derived image —
see [Add plugins](#add-plugins).

The image entrypoint is `tai` and its default command is `serve`. Three
long-lived processes come out of the same image:

| Process | Command | What it does |
| - | - | - |
| serve | `tai serve` | The HTTP API, the MCP endpoint, and the Studio, on one origin. |
| backend worker | `tai backend worker` | Runs queued, scheduled, and agent work. |
| metrics | `tai metrics` | Serves the Prometheus multiprocess endpoint. |

A one-shot `db-migrate` step runs `tai db migrate`, and `serve` and `backend`
wait for it to complete before they start. It applies the ordered migration chain
— the core plus each installed plugin that owns one — and is idempotent: a run
with nothing pending is a no-op. Each app container also refuses to serve on an
out-of-date database, so a missed migration is a loud refusal, not a broken serve.

> [!NOTE]
>
> The official `docker.io/tai42/tai` image (mirrored at `ghcr.io/tai42ai/tai`) is
> what the Compose bundle runs — signed, scanned, and multi-arch. Pin
> a release tag in production and verify its signature; the
> [quickstart](/self-hosted/quickstart)'s build-from-source is a dev-only
> alternative. See [Self-hosted](/self-hosted) for the image, upgrades, and
> artifact verification.

Boot it step by step in the [Self-hosted quickstart](/self-hosted/quickstart) —
`git clone`, the `.env` secrets, the `config/` bind mount, `docker compose up`,
the opt-in profiles, and the dev-only build-from-source. Only `serve` publishes a
port; Postgres, Redis, and the optional MinIO and RabbitMQ services stay on the
Compose network.

## Configure the bundle

The Compose bundle reads a small set of variables from `.env`; everything else is
fixed in the file and points the services at each other.

```bash theme={null}
TAI_VERSION=latest                    # image tag; pin a release in production
TAI_SERVE_PORT=8000                   # host port for serve
POSTGRES_USER=tai
POSTGRES_DB=tai
POSTGRES_PASSWORD=                    # required — openssl rand -hex 24
ACCESS_CONTROL_ENABLE=false           # the auth-free quickstart shape
TAI_BACKEND_MODULE=tai42_backend_arq  # which backend the worker runs
```

`POSTGRES_PASSWORD` has no default: Compose refuses to start until it is set.
The `minio` and `celery` service profiles add `MINIO_ROOT_USER`,
`MINIO_ROOT_PASSWORD`, `STORAGE_S3_BUCKET`, `RABBITMQ_USER`, and
`RABBITMQ_PASSWORD`. Those profiles drive the S3 storage and celery backend
plugins, which are not in the minimal image — [add the plugin](#add-plugins)
before enabling the profile.

The bundled `postgres` and `redis` services back the `default` named database and
the shared Redis namespace, so every core Postgres store — the access-control
policy store, the connector store, the marketplace store, the versioning store,
and the tool-metadata overlay — plus their migrations and every Redis-backed
feature resolve without further configuration.

## Add plugins

The image is the minimal core. A deployment adds the plugins it needs one of two
ways.

**Runtime, through the marketplace.** A running server installs, updates, and
uninstalls plugins against itself — it `pip install`s the package into its own
environment, patches the [manifest](/concepts/manifest), and reloads, so the
plugin is live with no restart — router/middleware and channel inbound routes
come live on that same reload, whose epoch rebuild re-imports the plugin and
re-registers its routes. See [Install a plugin](/marketplace/install). For
those installs to survive a container recreation, the server's plugin-prefix
setting must point at a mounted, persistent directory — see [the persistent
mounts](/self-hosted/quickstart#the-persistent-mounts).

**Build time, in a derived image.** Bake a fixed roster into your own image on
top of the core, then name the added modules in your manifest:

```dockerfile theme={null}
FROM docker.io/tai42/tai:latest
# The base image ends on USER tai over a root-owned venv, so become root to
# install, then drop back to the non-root runtime user. Use `python -m pip`
# (the venv interpreter is first on PATH; a bare `pip` would be the base
# image's system pip and install outside the venv, where the server never
# looks).
USER root
RUN python -m pip install tai42-channel-slack tai42-storage-s3
USER tai
```

A marketplace install writes two things a real deployment must keep across a
container recreation — the installed plugin **code** (`TAI_PLUGINS_PREFIX`) and
its **registration** in the manifest (`TAI_MANIFEST_PATH`). Persist both on their
own mounts, or a recreated container boots with the code and its registration out
of sync. The [persistent mounts](/self-hosted/quickstart#the-persistent-mounts)
cover the two volumes in full.

> [!WARNING]
>
> `.env.example` ships `ACCESS_CONTROL_ENABLE=false` — the quickstart shape. Turn
> it on before anything but a laptop, and register an identity provider in the same
> change: with access control on and no provider, the runtime refuses to boot.

## Turn on access control

Set `ACCESS_CONTROL_ENABLE=true` and register a provider in the manifest. The
bundled default is the Redis-backed API-key provider, which the image already
installs:

```yaml manifest.yml theme={null}
lifecycle_modules:
  - tai42_identity_redis.redis_api_key_provider
```

Then initialize the deployment with the one-shot [`tai setup`](/reference/cli/setup)
door — gated by `TAI_SETUP_TOKEN` or the auto-generated token logged once at
startup, and refused as soon as the owner exists — which creates the owner and
prints its first admin key once. Write the policy that key resolves to. [Access control](/concepts/access-control) covers
the policy model, and the [access-control guide](/guides/access-control) walks
the first key end to end.

No token is logged when you pin `TAI_SETUP_TOKEN`, when no configured provider can
mint keys, when the access-control Redis is unset, or when access control is off — the
last three refuse the door with a `501`; [initializing a deployment whose logins are OIDC](/guides/access-control#initializing-a-deployment-whose-logins-are-oidc)
covers the case where every human signs in through OIDC.

`ACCESS_CONTROL_ALWAYS_PUBLIC_PATH_PREFIXES` selects further paths served without a
key. The login routes need no entry — each declares itself a public
[pre-authentication route](/concepts/access-control#routes-declare-their-reach) — and
the app sets none itself. The bundle's value names the Studio's static assets (and
`/api/login`, which the declarations already cover):

```bash theme={null}
ACCESS_CONTROL_ALWAYS_PUBLIC_PATH_PREFIXES='["/api/login", "/assets", "/vendor", "/favicon.ico", "/tai42-logo-icon.png", "/apple-touch-icon.png", "/"]'
```

`/health` and `/ready` are deliberately absent: the app already serves them
public by route-level declaration, and listing them here is rejected at boot as a
conflict.

For human sign-in — sessions, roles, invites, and the first admin — add the
accounts provider described in [Accounts](/operate/accounts).

## Run on Kubernetes

The same image runs on Kubernetes with `serve` and `backend` as separate
workloads and the datastores pointed at managed Postgres and Redis. The
marketplace-install persistence model is the platform-side piece to get right:

> [!NOTE]
>
> Marketplace installs on Kubernetes need the plugin-prefix directory on a shared,
> persistent volume (a `ReadWriteMany` PVC) so every `serve`
> and `backend` pod sees the same installed code, plus the manifest on persistent
> storage. An install `pip install`s into the one pod that handled the request and
> broadcasts the manifest reload fleet-wide — the other pods only reload the
> manifest, so unless the prefix is shared they try to import a package they do not
> have. `serve` and `backend` are separate Deployments — two pods even at one
> replica each — so `ReadWriteOnce` suffices only when a single node holds every
> mounting pod (disable `backend`, or co-schedule the two onto one node); otherwise
> the shared `ReadWriteMany` mount is required. Every marketplace install/upgrade
> ends in a fleet reload broadcast on the worker bus, so already-running peer pods
> re-import the changed plugin in place — one pod installs, the others pick it up
> live with no restart — **router** and **middleware** plugins and a channel's
> inbound webhook route included: the reload rebuilds the serving epoch, which
> re-imports the plugin package and its route-sibling modules and re-registers the
> declared routes, so a net-new or upgraded router serves after the swap without a
> pod restart. Fleets that want fully static rosters can bake them into a
> [derived image](#add-plugins) instead.

## TLS and the front door

`serve` speaks plain HTTP on its published port, and the Compose bundle puts
nothing in front of it. Terminate TLS at your own reverse proxy or load balancer
and forward to that port.

On Kubernetes a single-host, single-path Ingress is enough — the Studio and the
`/api` surface share one origin, so there is nothing to split — with TLS
terminated at the Ingress.

Some features need the public origin spelled out rather than inferred:
[connectors](/concepts/connectors) accept an OAuth redirect only when its origin
is listed in `CONNECTORS_REDIRECT_URI_ALLOWLIST`.

## See also

* [Deploy](/operate/deploy) — transports, workers, and the serving modes.
* [Back up and restore](/operate/backup-and-restore) — what state to capture.
* [The layering](/concepts/layering) — what the image actually contains.


# Infrastructure by feature
Source: https://docs.tai42.ai/operate/infrastructure

Which features need Postgres, Redis or another service, which need nothing, and what happens when the service is missing.

Most of the platform runs with no services at all. A feature that needs Postgres,
Redis or another service says so on this page, names the setting that points at it,
and says what happens when it is missing.

A missing service shows up in one of four ways:

* **Boot refused.** The server does not start, and the error says why.
* **Off.** The feature reports itself off. Reads answer empty and writes answer `501`
  with a code that names the feature (see [What OFF looks like](/concepts/config-and-secrets#what-off-looks-like)).
* **In memory.** The feature works inside one process only, and boot logs a `WARNING`
  where the table says so.
* **Fails at first use.** Boot succeeds. The first call that needs the service raises
  an error that names the setting.

## How the settings resolve

* **Postgres.** A Postgres feature uses the [named database](/concepts/config-and-secrets#named-databases)
  its component binds to. A component binds to `default` unless `TAI_DB_BINDING_<COMPONENT>`
  says otherwise, so most features read `TAI_DATABASE_DEFAULT_PG_*`. A database counts as
  configured when its password is set. Set its host too: a password with no
  `TAI_DATABASE_<NAME>_PG_HOST` raises when the first connection is built.
* **Redis.** Each Redis feature has its own `<PREFIX>REDIS_URL`. When that is unset it
  uses the shared `TAI_DEFAULT_REDIS_URL`. Setting the shared URL turns on every Redis
  feature at once (see [Default connection namespace](/concepts/config-and-secrets#default-connection-namespace)).
* **Plain Redis or Redis with modules.** Almost every feature runs on any standard
  `redis-server` with no modules (`redis:7`, `redis:8` or Valkey). The `redis` checkpoint store and the
  `redis` LLM store, both the default, are the exceptions: they need the JSON and search
  modules. Redis 8 ships both, and the Compose bundle's Redis is Redis 8. A Redis 7 needs
  RedisJSON and RediSearch loaded. On a plain Redis the store's setup fails with
  `unknown command 'FT._LIST'`.

## The minimal deployment

A single `tai serve` worker with the `file` config mode and access control off needs
no Postgres and no Redis. Local tools and mounted MCP servers work. Each feature that
needs a service behaves as the tables below say.

```bash theme={null}
export ACCESS_CONTROL_ENABLE=false
tai serve --transport http --host 127.0.0.1 --port 8000
```

Two defaults need a service unless you change them:

* **Access control is on by default.** With it on, the server needs an identity
  provider plugin, Postgres and Redis. See the core table.
* **The checkpoint store defaults to `redis`.** An agent or flow run needs a
  checkpoint store. Set `LLM_PROVIDER_CHECKPOINT=memory` for local work, or give it a
  Redis with modules or a Postgres. See the core table.

## Core

| Feature | What it needs | Setting | Without it |
| - | - | - | - |
| Tools, MCP mounts, manifest | Nothing | — | — |
| Worker bus | Plain Redis | `TAI_BUS_REDIS_URL` | One worker in `file` mode runs on a local no-op bus. Boot is refused for more than one `tai serve` worker, a config mode other than `file`, or a registered execution backend. See [Worker bus](/concepts/worker-bus). |
| Access control (on by default) | An identity provider plugin, Postgres (the `skeleton` database), and plain Redis for the gate's live context | `ACCESS_CONTROL_ENABLE`, `TAI_DATABASE_<NAME>_PG_*`, `ACCESS_CONTROL_REDIS_URL` | No identity provider: boot is refused. No Postgres or no gate Redis: the server boots, and every request that carries a key is denied with `Access Denied`, with the error logged. Set `ACCESS_CONTROL_ENABLE=false` to run without auth. |
| Schema check | Postgres (the `skeleton` database) | `TAI_DATABASE_<NAME>_PG_*` | The check is skipped. With a database set and a migration pending, boot is refused with `Run 'tai db migrate'`. |
| Background tool runs | Plain Redis | `TAI_TOOL_RUNS_REDIS_URL` | Off. |
| Interactions and notifications | Plain Redis | `INTERACTIONS_REDIS_URL` | Off. |
| Rate limiting on public doors | Plain Redis | `TAI_RATE_LIMIT_REDIS_URL` | Public doors are not throttled. Boot logs one `WARNING`. |
| Hooks | Plain Redis | `HOOKS_REDIS_URL` | In memory, with a `WARNING`. Each `tai serve` worker refuses to boot without it when there is more than one worker, and boot is refused for a registered execution backend at any worker count. |
| Conversations | Plain Redis | `CONVERSATIONS_REDIS_URL` | In memory, with a `WARNING`. Every routing operation answers `501`. |
| Sub-MCP registrations | Plain Redis | `SUB_MCP_REDIS_URL` | In memory. Each `tai serve` worker refuses to boot without it when there is more than one worker. |
| Marketplace store, tool metadata, versioning and settings profiles | Postgres (the `skeleton` database) | `TAI_DATABASE_<NAME>_PG_*` | Off. See [OFF behavior per feature](/concepts/config-and-secrets#off-behavior-per-feature). |
| Subject state records | Postgres (the `states` database, bound to `default` unless `TAI_DB_BINDING_STATES` names another) | `TAI_DB_BINDING_STATES`, `TAI_DATABASE_<NAME>_PG_*` | Off. With its database set and a migration pending, boot is refused with `Run 'tai db migrate'`. |
| Run index | Postgres (the `skeleton` database) | `TAI_DATABASE_<NAME>_PG_*` | Runs are not indexed. |
| Connectors | Postgres (the `skeleton` database), plain Redis, and the `CONNECTORS_*` keys | `TAI_DATABASE_<NAME>_PG_*`, `CONNECTOR_STORE_REDIS_URL` | No Postgres: off. No Redis: the token cache reads Postgres, with a `WARNING`, and starting an OAuth connection fails at first use. |
| Checkpoint store for agent and flow runs | `redis` (default): Redis with the JSON and search modules (Redis 8). `postgres`: Postgres. `memory` or `sqlite`: nothing (development only). | `LLM_PROVIDER_CHECKPOINT`, `LLM_PROVIDER_CHECKPOINT_CONN_STRING` | Fails at first use. With no conn string, `redis` reads `REDIS_URL` or `TAI_DEFAULT_REDIS_URL`, and `postgres` reads the base `PG_*` settings. See [Checkpoints](/operate/checkpoints). |
| LLM store (retrieval and deep agents) | `redis` (default): Redis with the JSON and search modules (Redis 8). `postgres`: Postgres. `memory` or `sqlite`: nothing. | `LLM_PROVIDER_STORE`, `LLM_PROVIDER_STORE_CONN_STRING` | Fails at first use. |
| Schedules | An execution backend plugin that exposes scheduling | — | Answers `501`. |
| Storage | A storage provider plugin | `storage_module` in the manifest | Answers `501`. |

`tai doctor` checks the `skeleton` database (with the migrator identity), its schema,
and the connector-store Redis (`CONNECTOR_STORE_REDIS_URL` or `TAI_DEFAULT_REDIS_URL`).
It counts an unconfigured one as a failure and exits non-zero. It does not check the
other Redis features.

## Plugins

| Plugin | What it needs | Setting | Without it |
| - | - | - | - |
| [`identity-redis`](/plugins/tai42/identity-redis) | Plain Redis | `TAI_IDENTITY_REDIS_URL` | Boot is refused: the provider's health check reads Redis at startup. |
| [`accounts-postgres`](/plugins/tai42/accounts-postgres) | Postgres, and plain Redis for the login throttle | `TAI_DB_BINDING_TAI42_ACCOUNTS_POSTGRES`, `TAI_ACCOUNTS_REDIS_URL` | No database: the boot schema check is skipped. A pending migration refuses boot. |
| [`agents`](/plugins/tai42/agents) | An LLM provider; the core checkpoint store; plain Redis for parking and the workspace lease; a sandbox provider for `claude_code` and `langchain_deep_agent`; the LLM store and an embedding provider for `retrieval_tools_agent` | `LLM_PROVIDER_*`, `TAI_AGENTS_REDIS_URL`, `sandbox_module` | A park without a durable checkpoint store or the agents Redis is refused. A sandbox agent without a sandbox provider fails at first use. |
| [`backend-arq`](/plugins/tai42/backend-arq), [`backend-rq`](/plugins/tai42/backend-rq) | Plain Redis, the worker bus, and the shared hooks registry | `ARQ_REDIS_URL`, `RQ_REDIS_URL` | With both its own URL and `TAI_DEFAULT_REDIS_URL` unset, it connects to `redis://localhost:6379/0` and fails there. No bus or an in-memory hooks registry: boot is refused. |
| [`backend-celery`](/plugins/tai42/backend-celery) | A broker (AMQP such as RabbitMQ, or Redis), a result backend, Redis for the beat schedule, the worker bus, and the shared hooks registry | `CELERY_BROKER_URL`, `CELERY_RESULT_BACKEND`, `CELERY_REDBEAT_REDIS_URL` | An unset broker uses `TAI_DEFAULT_REDIS_URL`, else `amqp://localhost:5672//`. No bus or an in-memory hooks registry: boot is refused. |
| [`channel-slack`](/plugins/tai42/channel-slack), [`channel-twilio`](/plugins/tai42/channel-twilio), [`channel-whatsapp`](/plugins/tai42/channel-whatsapp) | The vendor's account, a public HTTPS URL for inbound, and plain Redis | `CHANNEL_<NAME>_REDIS_URL` | No Redis: fails at first use. |
| [`channel-telegram`](/plugins/tai42/channel-telegram) | A bot token, a public HTTPS URL, and plain Redis | `CHANNEL_TELEGRAM_*`, `CHANNEL_TELEGRAM_REDIS_URL` | Boot is refused without the token, webhook secret, public URL, and a recipient or allowlist, or when Telegram rejects the webhook. No Redis: fails at first use. |
| [`channel-web`](/plugins/tai42/channel-web) | Plain Redis | `CHANNEL_WEB_REDIS_URL` | Every door except the asset door answers `501` with `web_transcript_store_off`. |
| [`connector-atlassian`](/plugins/tai42/connector-atlassian), [`connector-github`](/plugins/tai42/connector-github), [`connector-google`](/plugins/tai42/connector-google), [`connector-slack`](/plugins/tai42/connector-slack) | The vendor's OAuth app, and the core connectors store | `CONNECTORS_<NAME>_CLIENT_ID`, `CONNECTORS_<NAME>_CLIENT_SECRET` | Starting a connection fails, naming the missing variable. |
| [`mcp-dynamic-postgres`](/plugins/tai42/mcp-dynamic-postgres) | Postgres | `PG_HOST`, `PG_DB`, `PG_USER`, `PG_PASSWORD` | The server fails at startup without `PG_DB`, `PG_USER` or `PG_PASSWORD`. |
| [`monitoring-langfuse`](/plugins/tai42/monitoring-langfuse) | A Langfuse project and an OTLP endpoint | `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `LANGFUSE_HOST`, `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | When `monitoring_module` selects it, boot is refused without the three `LANGFUSE_*` keys. |
| [`sandbox-docker`](/plugins/tai42/sandbox-docker) | A Docker daemon | `SANDBOX_DOCKER_HOST` | The sandbox reaper stops soon after start, `/ready` answers `503`, and the process exits. |
| [`sandbox-local`](/plugins/tai42/sandbox-local) | A local directory, no isolation | `SANDBOX_LOCAL_ROOT` | — (development only) |
| [`storage-local`](/plugins/tai42/storage-local) | A local directory | `STORAGE_LOCAL_ROOT_PATH` | Fails at first use. |
| [`storage-s3`](/plugins/tai42/storage-s3) | S3 or S3-compatible object storage | `STORAGE_S3_BUCKET`, `STORAGE_S3_*` | Fails at first use. |
| [`storage-github`](/plugins/tai42/storage-github) | A GitHub repository and a token | `STORAGE_GITHUB_USERNAME`, `STORAGE_GITHUB_REPO`, `STORAGE_GITHUB_TOKEN` | Fails at first use. |
| [`toolbox`](/plugins/tai42/toolbox) | Nothing. `classify` and `generate_embeddings` need an LLM or embedding provider. | — | — |
| [`tools-github`](/plugins/tai42/tools-github), [`tools-stripe`](/plugins/tai42/tools-stripe), [`tools-twilio`](/plugins/tai42/tools-twilio), [`tools-whatsapp`](/plugins/tai42/tools-whatsapp) | The vendor's API credentials | the plugin's own token variable | Every tool call fails, naming the variable. |
| [`webhook-verifier-github`](/plugins/tai42/webhook-verifier-github), [`webhook-verifier-stripe`](/plugins/tai42/webhook-verifier-stripe) | A signing secret | the variable the hook binding names | The hook door refuses the request. |

## Premium plugins

| Plugin | What it needs | Setting | Without it |
| - | - | - | - |
| `config-kubernetes` | The Kubernetes API (read and update the Secret, read and patch the ConfigMap), and the worker bus | `TAI_CONFIG_MODE=kubernetes`, `CONFIG_K8S_*` | No bus: boot is refused. |
| `sandbox-kubernetes` | The Kubernetes API (pods, `pods/exec`, PVCs, NetworkPolicies) | `SANDBOX_K8S_NAMESPACE`, `SANDBOX_K8S_*` | No namespace: the sandbox reaper stops soon after start, `/ready` answers `503`, and the process exits. |
| `identity-oidc` | An OIDC issuer | `TAI_IDENTITY_OIDC_ISSUER`, `TAI_IDENTITY_OIDC_AUDIENCE` | Boot is refused without them, or when the issuer's discovery or JWKS cannot be fetched. |
| `accounts-oidc` | OIDC issuers, plain Redis for sessions and login state, and Postgres for the invitation flow | `TAI_ACCOUNTS_OIDC_*`, `TAI_ACCOUNTS_OIDC_REDIS_URL`, `TAI_DB_BINDING_TAI42_ACCOUNTS_OIDC` | Boot is refused without `TAI_ACCOUNTS_OIDC_STATE_KEY` and `TAI_ACCOUNTS_OIDC_PUBLIC_BASE_URL`, when an issuer cannot be reached, or when its Redis (`TAI_ACCOUNTS_OIDC_REDIS_URL`, or `TAI_DEFAULT_REDIS_URL` when unset) is unset, unreachable, or lacks `GETDEL` (Redis 6.2 or later). `/ready` answers `503` when that Redis stops answering. |

## Flows engine

| Feature | What it needs | Setting | Without it |
| - | - | - | - |
| Flow checkpoints (on by default) | The core checkpoint store | `FLOW_CHECKPOINT_ENABLED`, `LLM_PROVIDER_CHECKPOINT` | With the `redis` store and no Redis URL, boot is refused. A plain Redis fails at the first run. |
| Async park | A durable checkpoint store (`redis` or `postgres`) and the engine Redis | `LLM_PROVIDER_CHECKPOINT`, `FLOW_REDIS_URL` | No durable store: the park is refused. No engine Redis: the park fails when it writes its index. |
| Run status and abort across workers | Plain Redis | `FLOW_REDIS_URL` | Status and abort see only the runs in the same process. |
| Flow states | Postgres | `TAI_DB_BINDING_FLOWS_STATES` | Off unless the binding is set: the routes answer `503` with `states_unavailable`. With the binding set, an unconfigured database or a pending migration refuses boot. |

## Development only

These shapes are fine on a laptop and wrong in production:

* `ACCESS_CONTROL_ENABLE=false`: no auth on any request.
* `LLM_PROVIDER_CHECKPOINT=memory` or `sqlite`: runs do not survive a restart and cannot park.
* `sandbox-local`: sandboxed code runs on the host with no isolation.
* One worker with in-memory hooks, conversations and sub-MCP registrations.
* `CHANNEL_WEB_SESSION_COOKIE_SECURE=false`: the web chat cookie over plain HTTP.

## See also

* [Deploy](/operate/deploy): workers, config mode, and access control at deploy.
* [Config and secrets](/concepts/config-and-secrets): named databases and the shared Redis default.
* [Checkpoints](/operate/checkpoints): the checkpoint stores and their retention.


# Manage a fleet
Source: https://docs.tai42.ai/operate/manage-a-fleet

Read the live worker census, inspect the backend, and drive fleet-wide operations.

Read the live worker census, inspect the execution backend, and soft-restart the fleet — all without dropping a process.

A fleet is every process that shares one manifest. A single-worker server is a fleet of one: a live change (a tool reload, a preset rebind, a manifest update) applies in that process and there are no siblings to reach. Run more than one process — multiple `tai serve` workers, or a `tai serve` fleet alongside a `tai backend` runtime — and the same mutation must reach every one of them. The [worker bus](/concepts/worker-bus) is what carries it there; the `tai fleet` group is the operator's window onto the fleet the bus coordinates.

## The bus is what makes a fleet, not a backend

Fleet convergence rides the app's own worker bus — internal infrastructure you enable with `TAI_BUS_REDIS_URL`, not a plugin you wire in the manifest. Any multi-process deployment needs it:

```bash theme={null}
export TAI_BUS_REDIS_URL="redis://localhost:6379/0"
```

The boot rules refuse a multi-worker `tai serve` server, a `kubernetes`-mode server, or a server with a registered backend when the bus is off — see [the worker bus](/concepts/worker-bus#boot-rules). A single-worker, `file`-mode, backend-free process is the one supported busless shape; it runs on a no-op local bus and is its own whole fleet.

## Wire a backend

A [backend](/concepts/backends) is a separate concern: a task runtime for background, scheduled, and distributed runs. It is optional, and it does **not** supply the fleet bus. Name a backend module to add that runtime, and set the bus and a shared hooks registry beside it (`HOOKS_REDIS_URL`, or `TAI_DEFAULT_REDIS_URL`): the backend process matches the events it raises against its own [hooks](/concepts/hooks#managing-hooks-live) registry, so a backend over an in-memory one is refused at any worker count:

```yaml examples/fleet/backend_manifest.yaml theme={null}
# Wire an execution backend by naming its module in the manifest. With no
# backend_module the calling process runs its own tools inline and the fleet is
# whatever HTTP workers share the manifest. A backend plugin (arq, celery, rq)
# adds a separate task runtime for background, scheduled, and distributed runs.
#
# A registered backend REQUIRES the worker bus — the backend-runtime and server
# processes must converge on config reloads — and a shared hooks registry — the
# backend runtime matches the events it raises against its own registry, and an
# in-memory one holds none of the hooks registered through the server. Set both
# (env vars, not manifest keys; placeholder host below; TAI_DEFAULT_REDIS_URL
# stands in for either) or the boot rules refuse to start:
#
#   TAI_BUS_REDIS_URL=redis://redis.internal:6379/0
#   HOOKS_REDIS_URL=redis://redis.internal:6379/0
backend_module: tai42_backend_arq
```

`tai fleet info` reports the registered backend's identity, or the empty state (`present: false`, a `200`) when none is wired. That empty state is about the backend only — the worker census and fleet reload work through the bus whether or not a backend is registered.

## Read the fleet

`tai fleet` is a thin wrapper over the authed backend and fleet routes — `info` reads `/api/backend` for the backend's identity, while `workers` (`/api/fleet/workers`) and `reload-config` (`/api/fleet/reload-config`) live under `/api/fleet/*` for the census and the soft restart:

```bash theme={null}
tai fleet info      # the registered backend's identity, or the empty state
tai fleet workers   # the live worker census — every process on the bus
```

`workers` lists every process subscribed to the bus — serving HTTP workers and any backend runtime alike — read from the presence census. It fails loudly: a store it cannot read is a `500`, never a silently empty fleet. Each row is one worker:

```console theme={null}
$ tai fleet workers
name       kind     pid    gen  state          seen-since  last-op
---------  -------  -----  ---  -------------  ----------  ---------------------
serve-1    serve    41201  3    ready          4s ago      reload_config:applied
serve-2    serve    41202  4    resyncing      1s ago      —
backend-1  backend  41250  2    ready (stale)  12s ago     reload_config:applied
backend-2  backend  41251  1    recycling      2s ago      reload_config:applied
```

The columns:

* **name** — the worker's stable slot (`{kind}-{n}`, e.g. `serve-1`). This is the value you pass to `--target`, and it stays the same across a restart.
* **kind** — `serve` or `backend`.
* **pid** — the OS process id of the current life.
* **gen** — the generation (life counter) for that slot; it advances each time a new process claims the name, so `serve-1` gen `4` is a later life than gen `3`.
* **state** — what the worker last wrote about itself: `ready` (serving), `resyncing` (running a boot or reconnect resync), or `recycling` (leaving under a recycle). A `(stale)` suffix means the row is past the freshness gate — its state can no longer be trusted (reconnecting or dead, unknown until it beats again or its row expires).
* **seen-since** — how long ago the worker last beat.
* **last-op** — the last op it applied and that op's outcome, or `—` if it has applied none.

Reading a restart in progress: a rolling restart or a recycle shows up here directly — `resyncing`/`recycling` rows with a fresh `seen-since` are workers mid-flight, a dead worker's row simply drops out when its TTL lapses, and a `ready` row that has gone quiet turns `(stale)` rather than being labelled reconnecting on a guess. The full subcommand set:

```bash examples/fleet/fleet_help.sh theme={null}
# The fleet group is the operator's window onto the worker fleet: info (the
# registered backend's identity), workers (the live census — every process on
# the bus), and reload-config (soft-restart the fleet).
tai fleet --help
```

## Soft-restart the fleet

`reload-config` is the fleet-wide soft restart: every worker refreshes its environment values and reloads the manifest registries in place, picking up configuration and capability changes without dropping its process. The soft restart carries every hot change in place; it never respawns a process, so a recycle-class value changed in the stored env since a worker bound it (a hand edit of `.env`, a `kubectl edit` of the config Secret) is named instead — see the `awaiting_respawn` list below. Restart the whole fleet, or restrict it to named workers with a repeatable `--target`:

```bash theme={null}
tai fleet reload-config
tai fleet reload-config --target serve-1 --target backend-2
```

`--target` takes worker slot **names** — the `name` column from `tai fleet workers` (`serve-1`, `backend-2`), not a pid or an opaque id.

The response is the per-worker fleet report — one row per worker with its reload outcome and, in its payload, `awaiting_respawn`: the recycle-class keys whose value differs from the one that worker bound (at boot, or when the plugin that declares them was loaded). A worker whose row names `awaiting_respawn` keys converged on everything a soft restart carries, and those keys take effect only when that worker is respawned: restart it through the deployment's supervisor (`kubectl rollout restart`, `docker compose restart <service>`; on a bare `tai serve`, restart the server) and verify the generation bump on `tai fleet workers`. The worker that ran the reload command logs one ERROR line naming every such worker and its keys. A worker the reload did not cleanly reach is named, never hidden: `departed` (it went away), `timed_out` (it acknowledged but is stuck past its drain budget), `missing` (alive but never acknowledged), or one of the gap outcomes `resyncing` (mid-resync), `recycling` (departing under a recycle), and `stale` (past the freshness gate, its state no longer trustworthy). A failed local apply raises; a remote miss is reported and logged. Re-run `reload-config` to converge the named workers.

## How a change reaches the fleet

Fleet reach is not a separate command — it rides every mutating operation. When a tool is reloaded or a capability is removed, the route persists the change, applies it locally, and then broadcasts it on the bus so every worker re-reads the durable state and rebinds; that response embeds the per-worker fleet report, so a propagation that did not converge is visible on the flow that caused it. A [preset](/concepts/presets) mutation broadcasts the same way, but its response is the plain preset record — a preset broadcast that does not converge is surfaced server-side as a loud non-convergence ERROR log rather than embedded in the response, and a fleet `reload_config` reconverges the named workers. See [live operations](/concepts/live-operations) for the mutation surface the bus backs.

**A `200` does not mean every worker converged.** A fleet broadcast applies the change locally first, then asks every reachable worker to confirm. The local apply is committed before the call returns, so the call returns `200` even when a sibling worker did not confirm — read the body: `ok` is `false` when any reachable worker has not converged, `reachable` tells you the bus was reached, and `results[]` carries each worker's `outcome` (`applied` means it converged; anything else — `resyncing`, `recycling`, `stale` — names a worker that did not). A client that only checks the HTTP status will miss an unconverged sibling: check `ok`. An env change that carries a recycle-class key — a profile apply or an env write — adds a second place to read: its `recycle` rows (an env write's response carries them under `recycle`, `null` when nothing recycled). Each row is `recycled` once the target's old life is gone and fresh capacity booted; a `timed-out` or `failed` row is where the roll stopped, with a `detail` naming why, and the targets after it — and the writer's own recycle — were not attempted. `recycle_stopped` names where the roll stopped and why (`null` when every target recycled); its `name` is empty when the bus could not be read before a target was reached. Its `awaiting_respawn` is the operation's verdict: the workers (name and keys) still awaiting a respawn after the roll — empty when the roll converged; a stopped roll leaves the workers it did not recycle listed, and the writer logs one ERROR line naming them. A non-2xx is reserved for a local apply that itself failed or a malformed request — a case where the change did NOT land.

To recover a worker named `timed-out` or `failed`: watch `tai fleet workers` — a target the bus could not confirm may still recycle once its reload returns, and its generation bumps. A `failed` row or a stop whose detail names the bus is verified on `tai fleet workers` once the bus answers: a target the recycle op reached may have recycled (its generation bumped). One that did not is restarted through the deployment's supervisor, then verified on the census.

## See also

* [The worker bus](/concepts/worker-bus) — the internal fan-out primitive and its boot rules.
* [Backends](/concepts/backends) — the optional task-execution runtime.
* [Live operations](/concepts/live-operations) — the reload/remove/update surface that broadcasts across the fleet.
* [Deploy](/operate/deploy) — scaling to multiple workers and the durable stores a fleet needs.
* [CLI reference](/reference/cli) — the full `tai fleet` surface.


# Observe
Source: https://docs.tai42.ai/operate/observe

Collect metrics and traces, and enumerate runs.

Collect metrics and traces from a running server, and enumerate its runs.

The runtime records what runs. Tool and agent runs produce traces; aggregate counts and latencies roll up into metrics; a platform-side runs index enumerates every preset run. You query all three from the CLI. A monitoring backend plugin persists and serves the metrics and traces; the `monitor` extension traces a standalone tool call as one span.

## Query metrics

Query aggregate metrics over a time range. `--from` and `--to` take an ISO instant or a relative token (`7d`, `30d`); `--granularity` is `hour`, `day`, or `week`.

```bash theme={null}
tai obs metrics --from 7d --granularity day
```

## List and read traces

**1. List runs**

List observability runs, or download the filtered list with `--export`.

```bash theme={null}
tai traces list
```

**2. Read one trace**

Get one run's full trace, or download it as JSON with `--export`.

```bash theme={null}
tai traces get <run-id>
```

Narrow the list to one subject with the [identity
dimensions](#the-identity-dimensions) the runtime stamps: `--user`, `--session`,
and `--version` filter to one person, one conversation thread, or one preset
version.

```bash theme={null}
tai traces list --user person_7f3a --from 7d
```

## Reading traces

A trace is a tree of spans. Every span carries a neutral **kind** the monitoring
backend maps its own observation types onto:

| Kind | What it is | Studio body |
| - | - | - |
| `LLM` | a model call | the messages, one bubble per message |
| `TOOL` | a tool call | Arguments / Result |
| `CHAIN` | a step that runs other work: a graph node, a run's root | Input / Output |
| `EVENT` | a point-in-time marker | Input / Output |

A span reports its token counts as `inputTokens`, `outputTokens` and `totalTokens`,
each `null` when the producer reported none. A model call's input and output are
recorded in the OpenTelemetry GenAI message shape — a list of `{role, parts}`
messages, each part a `text`, a `tool_call`, a `tool_call_response` or another typed
part, and an output message's `finish_reason` — and the Studio renders each part by
its type. A value that is not in that shape shows as a JSON tree, so every value
stays visible.

![The trace view with a model-call span selected, its user prompt and its output message shown as text, the output with a 'finish: stop' footer.](https://mintcdn.com/tai42/jD9sf4htAEuXkH0Z/images/studio/trace-llm-parts-light.png?fit=max\&auto=format\&n=jD9sf4htAEuXkH0Z\&q=85\&s=bf7e0e9915b8093162016a595fd329af)

A model call's span detail: the input and output messages rendered part by part, the output with its finish reason.

A step's input or output may hold **references** to values other steps recorded
first (see [Each value recorded once](#each-value-recorded-once)). The Studio's span
detail says how many references a value holds and offers **As recorded** (the tree
opens to every reference within 64 levels of the value's root — one level per object key or
array index — and shows it as it is stored: the span id, the field and the pointer it names;
a reference nested deeper is neither counted nor opened) or
**Resolved** (the full value, assembled by the server). A referenced value the
backend does not hold yet, or has lost, says so and offers the recorded view back.
**Download resolved** in the trace view exports the whole trace with every reference
resolved. A value marked `{"$tai42_unrecorded": true}` was produced while monitoring
was off; the Studio notes it under the tree.

![A span detail reading 'Recorded with 1 reference to other steps.' with the As recorded view selected and the reference, its span id and its pointer visible in the tree.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/trace-references-recorded-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=5d098a5f0cabe2a61cab3fbeeee5a593)

A step's input as recorded: one reference to another step's output, shown with its span id and pointer.

![The same span detail with the Resolved view selected, showing the assembled value and 'Full value assembled from 1 reference.'](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/trace-references-resolved-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=87ddc3db5d9b12649fea431c3160b6e2)

The same input resolved: the server assembles the full value from the referenced record.

![A span detail showing the panel 'A referenced value is missing from the monitoring backend' with a Show as recorded button.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/trace-reference-missing-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=1f2d61c294b59faeb2858dd9caeccbf1)

A reference to a record the backend does not hold: the Resolved view says so and offers the recorded view back.

Read the span tree without the span inputs and outputs — the light read for walking
a run's steps by `parentId` before opening a value:

```bash theme={null}
tai traces outline <trace-id>
```

```bash theme={null}
GET /api/observability/runs/{trace_id}/trace/outline
```

It serves every span of the trace with its parent, kind, status, timing, token
counts and producer metadata. It costs the backend what the full trace read costs;
only the response is smaller.

### What the backend serves

Each monitoring backend declares the largest run-list page it serves, the run-list
sorts it serves, and the filters each sort cannot be combined with. The run list
caps `pageSize` to that page maximum (never refusing a larger one), the export
drains pages of that size, and the Studio offers only the served sorts and disables
a filter the active sort cannot carry — a shared link that combines them drops the
sort.

```bash theme={null}
tai traces capabilities
```

```json theme={null}
{
  "pageSizeMax": 100,
  "sortKeys": ["createdAt", "cost", "latencyMs", "totalTokens"],
  "incompatibleFilters": {"cost": ["maxCost", "minCost", "status", "version"]},
  "metrics": {"measures": ["cost", "count", "latency", "tokens"], "dimensions": ["model"]}
}
```

(`GET /api/observability/capabilities`; the example is shortened.) A sort or
combination outside the declaration is refused by the backend with `501`.

![The Tracing tab under a cost sort with the Min cost, Max latency and the other filters that sort cannot carry disabled.](https://mintcdn.com/tai42/sBSjMnq3V3fvqaIU/images/studio/tracing-sort-guard-light.png?fit=max\&auto=format\&n=sBSjMnq3V3fvqaIU\&q=85\&s=89b127c206d3ccbfe55cb307996566ec)

The Tracing tab sorted by cost against a backend whose cost sort cannot carry the cost, latency, token, status and version filters: those filters are disabled.

## List runs without the vendor

The platform keeps its own **runs index**: one row per registered-preset run,
persisted in the platform's own Postgres — so a deployment enumerates its runs
without reaching for the monitoring backend at all. Each row carries the
run id, the preset name and version, the run's [attribution](#attribute-a-run-and-roll-up-cost)
user and session, its outcome, its start/end window, and the monitoring
`traceId` as a deep link into the full trace.

```bash theme={null}
tai runs list --preset support --outcome error
```

Filter by `--preset`, `--version`, `--user`, `--session`, `--interaction`,
`--outcome`, and a `--from`/`--to` start-time range; the same filters ride
`GET /api/runs` as query params. Outcomes are `running`, `success`, `error`,
`parked`, and `aborted` — a cancelled run records `aborted`, never `error`, and a
crash-interrupted run stays honestly `running` with no end time.

A run that parks on an async question and resumes later is two dispatches — two
rows. The shared `interactionId` joins them: the parked row records the
interaction it parked on, the resume's row records the same id, and
`--interaction <id>` returns that park's lifecycle pair.

A run that **resumes or takes** parked interactions itself — a door or tool
resolving [caller asks](/concepts/asking-the-caller) — records each id it acted on in
its `resumedInteractions` list, across its whole dispatch span, nested inline resumes
included (an inline resume opens no row of its own). The list is empty when the run
resumed nothing.

Rows are kept forever by default. Set `TAI_RUNS_INDEX_RETENTION_DAYS` and call
the prune on a cadence to bound the table:

```bash theme={null}
tai runs prune
```

> [!NOTE]
>
> Only a **registered preset** run lands in the index, stamped once at the
> outermost dispatch — a nested sub-preset adds no second row, and a raw tool call
> none. The index is fail-safe: a store outage never breaks a run.

## One run, one trace

A run that dispatches nested work keeps a single trace. A subflow invoked as a
tool and an agent driven as a flow node join the dispatching run's trace — their
spans nest inside it rather than minting a fresh, orphaned trace — so one participant
interaction reads end to end as one trace. A run that parks on an async question
and resumes later — days later, on another worker — rejoins its original trace.

One **feature** run is one trace, however many sub-runs it fans into internally.
An agent that drafts then critiques then finalises, or one that polls several
voters before a judge, nests every sub-run inside the feature's one trace rather
than opening a separate root per sub-run — so the whole feature run reads as a
single tree, with the sub-runs as nested spans.

A run dispatched directly — through the sync run-tool API, a background or
scheduled tool run, or the MCP `tools/call` edge — opens its own trace root when
no trace is already open, and nests under the existing root otherwise. That
decision is made once at the shared run chokepoint where the run record is
registered, agnostic to what the preset wraps. Every runs-index row therefore
carries a `traceId` deep link whenever a monitoring backend is active; with the
no-op default there is no trace to link.

## Every feature's model calls

Every platform feature's model calls are traced. The monitoring callback is
attached once at a shared seam that every agent kind passes through, so a
model-usage span lands on the run's trace whatever the kind — a flow-driven
agent, a multi-phase agent, or a voter-and-judge agent — and a new agent kind
inherits the coverage without wiring of its own. An agent that runs its model
calls inside its own sandbox session bypasses that seam and is covered a
different way, emitting its own usage (see the sandbox note under [Attribute a
run](#attribute-a-run-and-roll-up-cost) below). Model calls made inside a
**tool** are not a feature: trace those with the [`monitor`
extension](#trace-a-standalone-tool-call) instead.

The **classifier** is a feature's model call too, but it is its own model kind,
not a chat model, so it carries no chat-model callback. Each classifier call
still records a model-usage span on the run's trace — its model id, token usage,
provider request id, and the call's latency — resolved onto the run's trace by
the same lineage rule, or onto a fresh root for a standalone call. **Embeddings**
are not recorded as model calls.

## Send outcomes and delivery receipts

Every outbound channel send made inside a run's trace — a flow's `notify_user`
send, a question delivered to a person, an inbound participant notice — records a
`send:{channel}` span around the provider call. The span carries the recipient
as its input, and the `notify_user` seam adds the provider's message ids as its
output; a raised error marks it `ERROR` with the failure detail: `error.type`,
`error.kind` (`unknown` for an unclassified exception), `retryable`, and a
positive `retry_after` the medium asked for, stamped only alongside
`retryable: true`. A seam that retries emits one span per attempt, stamped with
`retry.attempt`, and there `retryable` is the seam's own decision: `true`
exactly when another attempt follows, `false` on the last one (the attempt
budget is spent, or too little of the ask's window is left for the backoff). So
"attempt 1 failed retryable, attempt 2 accepted" is visible rather than
collapsed. On a single send, `retryable` is the error's own classification
(`false` for an input error). A tool dispatched under a retry policy records the
same keys on each `tool-attempt:{tool}` span. These keys are ordinary span
metadata.

Acceptance is not delivery. On channels with a delivery-status webhook (WhatsApp,
Twilio), the provider's later status closes the loop: the status is resolved back
to the originating send and posted as a `delivery_receipt` event on that run's
trace, nested under its send span — a failed delivery as an `ERROR` event
carrying the provider's error detail. The receipt is **observability only**: it
annotates the trace, never re-sends, and never fails the flow.

A send on a channel with a bridge route is also a [send
record](/reference/conversation-bridge#send-records) in its conversation thread. When
nobody can tell whether such a send reached the participant — it passed its bound, it was
cancelled mid-call, an ask attempt timed out, or the process stopped after the record was
written — the record ends `outcome_unknown`, keeps the reason in its `error`, and is never
re-sent. Each such end logs a WARNING that names the record:

* a send that passed its bound or was cancelled mid-call:
  `conversations: send record <id> on <channel> to <address>: <error>; not re-sent`, where
  `<error>` is the record's `error` and ends "the outcome is unknown";
* a send record a stopped process left `sending`, settled by the sweep or the boot redrive:
  `conversations: send record <id> on <channel> to <address> was sent, outcome unknown: the
  process stopped before the medium answered; not re-sent`;
* an ask whose attempts timed out:
  `conversations: send record <id> on <channel> to <address> for interaction <interaction
  id>: delivery attempts [<numbers>] timed out unanswered; the participant may have received
  the question`, where the attempt numbers print as a list, for example
  `delivery attempts [1, 2] timed out`.

The thread listing's `?status=outcome_unknown` filter (`tai conversations threads <route> --status outcome_unknown`) finds a thread only while its **newest** record is
`outcome_unknown`; once a later record lands in the thread, the filter no longer finds it.
The failed listing (`tai conversations failed`) holds `failed` records only. To find every
`outcome_unknown` send, search the logs for the WARNINGs above (each names the record id);
to read one, open its thread's transcript (`tai conversations transcript <route> <thread>`), where each record shows its `delivery_status`, or the record itself (`tai
conversations get-message <route> <id>`), whose admin view holds its `error`.

> [!NOTE]
>
> A [conversation-bridge](/reference/conversation-bridge) reply is covered by
> **receipts, not spans**. Bridge delivery runs in a detached task after the turn's
> trace has closed, so a span there would attach to no run; the record's own delivery
> ledger and its delivery-status receipts are the authoritative accepted-versus-
> delivered signal for bridge messages instead. A `failed` from a reachable-channel
> refusal of a turn's reply also sends the participant a best-effort could-not-deliver
> notice — its own failure logged at `ERROR` and never retried — while a
> transport-exhaustion `failed`, or a refusal of an operator's hand-injected send, sends
> none; the failed-delivery listing and the trace event remain the signal either way.

> [!NOTE]
>
> The webhook wiring and per-channel status semantics live on the channel plugin
> pages: [channel-whatsapp](/plugins/tai42/channel-whatsapp) and
> [channel-twilio](/plugins/tai42/channel-twilio). A send outside any trace emits
> no span — a rootless span would attach to no run.

## Trace a standalone tool call

A tool call outside a flow or agent has no trace of its own. Load the `monitor` extension and stack it onto a tool to record the call as one live span. Load the module, then attach `monitor` to a tool.

```yaml manifest.yml theme={null}
extensions_modules:
  - tai42_skeleton.extensions.builtin.monitor

tools:
  - title: my_tools
    module: myapp.tools
    include: [greet]
    extensions:
      greet: [[monitor]]
```

When a flow or agent trace already owns the call, the extension suppresses its own span and just runs the tool.

> [!NOTE]
>
> Metrics and traces are served by a monitoring backend plugin, registered under `monitoring_module`. Without one, the runtime uses a no-op default and there is nothing to query.

## Attribute a run and roll up cost

Every run's trace can be tagged at the shared run chokepoint with the run's own
identity — the flow kwargs the operator defines per delivery, carried verbatim as
a `RunAttribution` of tags and metadata, wired once at the shared seam so every
door attributes. The attribution is set on the trace from its first span, so it
covers the whole run — the user, session, tags, and version are on the trace
before the first model or tool span opens, not attached to the later spans
alone. That lets you **group** cost and tokens by identity when you
query traces: per-delivery attribution, with no tenant system and no
per-tenant isolation — attribution only. Metrics aggregate over a time range
alone — `tai obs metrics` takes no identity filter, so slice by identity on the
trace list and roll the cost up from there.

There is **no cost-aggregation module**. Cost aggregation is a flow or a view built
over these attributed traces: the platform ships the generic attribution enabler,
and assembling spend into a cost view is delivery work on top of the trace data.

### The identity dimensions

Beyond the per-delivery tags, the runtime stamps every conversation-driven run
with generic identity at the same shared seam, and the monitoring backend maps
them to its native trace dimensions:

* **`user_id`** — person-id-first: a run with a resolved
  [person](/guides/link-a-person-across-channels) is attributed by that person's
  stable `person_id`, so one human's runs group together across channels. With no
  person it falls back to the raw `{channel}:{address}` the door saw, or the bare
  address on the API door.
* **`session_id`** — the resolved conversation thread, so a whole back-and-forth
  reads as one session.
* **`tags`** — the conversation route as `route:{name}`; a registered preset
  dispatch adds `preset:{name}` and `preset-v:{version}` and lifts the version
  onto the trace's native version dimension. Only the **outermost** preset
  stamps: a nested sub-preset never pollutes the root identity, and a draft run
  carries no preset stamp at all.

The run list filters by exactly those dimensions: `GET /api/observability/runs`
takes `user`, `session`, and `version` params, plus any number of
`meta.<key>=<value>` params — each one a string-equality clause on the trace's
metadata.

> [!WARNING]
>
> That identity is personal data, and it lands in **your** monitoring backend — so
> retention and erasure there are yours to govern. The platform sets no trace
> retention on your behalf, and [forgetting a
> person](/reference/conversation-bridge#forgetting-a-person) erases the bridge's
> own stores, never the monitoring backend's traces. Set a deliberate retention
> policy, and honour an erasure request by deleting the subject's traces keyed on
> their `user_id` — person-id-first attribution keeps a linked subject's
> cross-channel history under one deletable key. See the
> [monitoring-langfuse](/plugins/tai42/monitoring-langfuse) page for the
> backend-side duties.

> [!NOTE]
>
> Because the Claude Agent SDK's model calls run inside the sandbox session and
> bypass the platform LLM seam, the [`claude_code`](/guides/use-the-ready-made-agents)
> adapter emits the SDK-reported usage and cost into the active trace itself — so an
> attributed `claude_code` run's spend rolls up with everything else. Run standalone
> with no ambient trace, the adapter mints its own root trace carrying that
> model-usage span, so a standalone sandbox run is observable on its own rather than
> emitting nothing. The boundary:
> the toolbox `prometheus_metrics` extension records latency and count only; it is
> not the cost seam.

## The monitoring pipeline

Every monitoring backend records through one OpenTelemetry writer: each serve and
backend process exports OTLP over HTTP to an **OpenTelemetry collector** running as
its own container. The process encodes each recorded value once on the caller's
thread and hands spans to the SDK's batch processor; the protobuf encoding and the
network send run on the processor's worker thread, and the collector does the
batching, retrying, mapping to the backend's vocabulary, and the send. A deployment
changes backend by changing the collector's exporter and transform; the
[monitoring-langfuse](/plugins/tai42/monitoring-langfuse) page carries the Langfuse
mapping.

### Writer settings

The writer reads the OpenTelemetry SDK's own standard environment — no
platform-specific names.

| Variable | Required | Read by |
| - | - | - |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` (or `OTEL_EXPORTER_OTLP_ENDPOINT`) | yes — boot refuses without it | the OTLP exporter |
| `OTEL_PYTHON_SDK_INTERNAL_METRICS_ENABLED=true` | yes — boot refuses without it | the batch processor's drop counter |
| `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES` | no | the record resource |
| `OTEL_BSP_MAX_QUEUE_SIZE` / `_SCHEDULE_DELAY` / `_MAX_EXPORT_BATCH_SIZE` | no (2048 / 5000 / 512) | the batch processor |
| `OTEL_EXPORTER_OTLP_TRACES_TIMEOUT`, `…_COMPRESSION`, `…_HEADERS` | no | the OTLP exporter |
| `OTEL_METRIC_EXPORT_INTERVAL` | no (60000) | the drop-count collection; every flush collects too |

The value-length limits (`OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`,
`OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT`) have no effect: a recorded value is never
truncated.

### Each value recorded once

A model call records its input and output messages in full, in the OpenTelemetry
GenAI message shape, plus the generated message's full record; a tool call records
its arguments and result in full. A chain record (a graph node, its root) never
copies the run's data: a value already recorded appears as a **reference** to the
record that first holds it, the one-key object
`{"$tai42_ref": {"span_id", "field", "pointer"}}` (with a `trace_id` when the record
is in another trace). `{"$tai42_unrecorded": true}` marks a value that exists but was
produced while nothing recorded. A reference resolves through the reader:

```bash theme={null}
GET /api/observability/runs/{trace_id}/spans/{span_id}/resolved?field=input&pointer=/messages/0
GET /api/observability/runs/{trace_id}/trace/export?resolve=true
```

The first returns one field of one span (`pointer` is an RFC 6901 JSON pointer, empty
for the whole value) with every reference on the way and inside it resolved; the
second exports the whole trace resolved. The export's `resolve` is a boolean, `false`
when absent. `true`, `t`, `yes`, `y`, `on` and `1` read as true, and `false`, `f`, `no`,
`n`, `off` and `0` as false, each word in any case; any other value, the empty one and
one with surrounding spaces included, answers `400` with the field and the error type,
`{"error": [{"loc": ["resolve"], "type": "bool_parsing"}]}`. A reference the backend does not yet hold
(its ingestion is asynchronous) or has lost answers `502` with the reason "not yet
available or lost" — retry once ingestion catches up. Every `SecretValue` in a
recorded value is written as `[secret]`.

### Dropped and failed records are counted and alerted

Nothing the writer cannot deliver is silent. Every process counts it, and `/metrics`
serves the run family's totals:

| Counter | Counts |
| - | - |
| `tai42_monitoring_spans_dropped_total{reason="queue_full"}` | spans evicted by a full export queue |
| `tai42_monitoring_spans_failed_total` | spans in an export batch the collector did not accept |
| `tai42_monitoring_export_failures_total` | export calls that failed |
| `tai42_monitoring_attributes_dropped_total` | span attributes evicted over the span limit |
| `tai42_monitoring_records_failed_total` | records, or one field of a record, the writer could not build (an unencodable value is recorded as `{"$tai42_unencodable": "<type>"}`) |

Each growth of those totals raises one **`monitoring_export_failed`** platform event
within 15 seconds, whichever process of the family notices it first. Its payload is
the growth since the last alert:

```json theme={null}
{"spans_dropped": 0, "spans_failed": 12, "export_failures": 1, "attributes_dropped": 0, "records_failed": 0}
```

Bind a [hook](/concepts/hooks) on the topic to decide what an operator sees. The
hook's own run records nothing, so a dead collector never feeds itself. Readiness is
not tied to monitoring: a monitoring outage never pulls a serving worker.

The collector counts its own side on its telemetry endpoint (port `8888`). Alert on:

* **`otelcol_exporter_queue_size`** against `otelcol_exporter_queue_capacity` — the
  batches waiting to reach the backend. The collector retries a send it cannot make
  until it is delivered, so a backend that is down or unreachable (or an unset
  `LANGFUSE_HOST`) fails no span: the collector stays ready, logs each retry at
  `INFO`, and only this queue grows. A queue that keeps growing is the signal.
* **`otelcol_exporter_enqueue_failed_spans`** — spans refused because the queue is
  full.
* **`otelcol_exporter_send_failed_spans`** — spans the backend refused for good,
  logged at `ERROR` and dropped (for example, a missing or wrong
  `OTEL_COLLECTOR_LANGFUSE_AUTH` answered `401`).
* **`otelcol_receiver_refused_spans`** and **`otelcol_processor_refused_spans`** —
  spans the collector refused on intake (for example, over its memory limit).

### Write a monitoring backend

A backend plugin implements a **reader** for its backend and registers the shared
writer with it:

```python theme={null}
from tai42_contract.app import tai42_app
from tai42_kit.monitoring.otel import OtelWriter


@tai42_app.monitoring.register_monitoring
def my_monitoring():
    return MyMonitoring(
        writer=OtelWriter(resource_attributes={"deployment.environment.name": "prod"}),
        reader=MyReader(),
    )
```

The reader implements `MonitoringReader`. Beside the reads, it declares what it
serves and maps its own vocabulary onto the neutral one:

* `get_observation(trace_id, observation_id)` returns one observation with its full
  input and output — the call references resolve through.
* `list_capability()` returns a `ListCapability`: the `OrderBy.field` values
  `list_traces` serves, and for each sort the `MonitoringFilter` field names it cannot
  combine with. `list_traces` raises `MonitoringReadNotSupportedError` outside it.
* `max_page_size()` returns the largest `limit` one `list_traces` call accepts; a
  larger `limit` raises `ValueError`.
* Each `MonitoringObservation` carries a `kind` (`LLM`, `TOOL`, `CHAIN` or `EVENT`)
  mapped from the backend's own observation type, and the `input_tokens`,
  `output_tokens` and `total_tokens` the producer reported.
* Each `MonitoringTraceSummary` carries the trace's own `input` and `output`; the
  platform bounds them for the run list.
* `list_spans_in_window` selects steps by the producers' marker, never by span
  names: a record whose metadata `tai42.step_role` is `grouping` or `sub_step` is
  never an item, and neither is a model call nor an event.

The backend's attribute vocabulary lives in the collector config, never in the
process. Registration refuses a backend whose writer or reader lacks a member of its
protocol, naming the members.

## Pending state saves

The [state store's pending saves](/concepts/states#pending-saves) publish Prometheus metrics on
the server's `/metrics` (the multiprocess-aware registry). Counters:
`tai42_state_outbox_enqueued_total`, `tai42_state_outbox_applied_total{phase}`,
`tai42_state_outbox_attempt_failures_total{phase,kind}`, `tai42_state_outbox_failed_total{phase}`,
`tai42_state_outbox_divergences_total` (an apply whose answer differed from the run's
projection), `tai42_state_outbox_discarded_total`, `tai42_state_outbox_retried_total`,
`tai42_state_outbox_lock_waits_total`, `tai42_state_outbox_notify_failures_total`,
`tai42_state_outbox_sweep_errors_total`, and `tai42_state_outbox_drain_waits_total{door}`
(`door` is `read` or `run_entry`). Histograms: `tai42_state_outbox_drain_wait_seconds{door}` and
`tai42_state_outbox_apply_latency_seconds` (enqueue to records applied). Gauges, set by each
sweep pass: `tai42_state_outbox_rows{status}` and `tai42_state_outbox_oldest_age_seconds`.

Set alert rules on three of them: any increase of `tai42_state_outbox_failed_total` (a save
failed and holds its subjects), `tai42_state_outbox_rows{status="failed"}` above zero (a held
save still waits for an operator), and `tai42_state_outbox_oldest_age_seconds` above a few sweep
intervals (saves are not being applied). The failed save itself is listed under
`tai states pending-saves list --status failed`.

## See also

* [Live operations](/concepts/live-operations) — status, retry, and runtime state.
* [The MCP-citizen surface](/concepts/mcp-citizen-surface) — progress and structured output that traces capture.
* [CLI reference](/reference/cli) — the full `tai obs`, `tai traces`, and `tai runs` surface.


# Sandbox
Source: https://docs.tai42.ai/operate/sandbox

Install one sandbox provider — container-isolated or direct-on-host — and wire the engine, durability, and egress.

A [sandbox](/concepts/sandbox) is the execution session an agent or a
`sandbox_exec` preset runs code in. The `sandbox` slot is a scalar single holder:
install exactly **one** provider, and which one you install **is** the execution
mode. The consuming agents keep one code path either way.

| Provider | Package | Engine | Isolation |
| - | - | - | - |
| `sandbox-docker` | `tai42-sandbox-docker` | Docker Engine API over a configured mTLS endpoint | an isolated container per session |
| `sandbox-local` | `tai42-sandbox-local` | the code runs directly on the host under `SANDBOX_LOCAL_ROOT` | **none** — direct on the host |

Each provider's full setup — its `<PREFIX>_*` settings and its engine
contract — lives on its own plugin page under the [Plugins section](/plugins):
`plugins/tai42/sandbox-docker` and `plugins/tai42/sandbox-local`. This page is the
operator narrative that gets you to them.

## Install and wire `sandbox-docker`

Install the provider, name its `sandbox_module` in the manifest, and point it at
an engine:

```bash theme={null}
tai plugins install tai42-sandbox-docker
```

* Set `SANDBOX_DOCKER_HOST` to the socket path or the `tcp://` engine endpoint.
* Mount the mTLS client certificates at the fixed path `/certs/client` (a volume
  mount, **not** an env var).
* No `TAI_MCP_SANDBOX` selector is needed — installing the plugin patches the
  `sandbox_module` in.

## Install and wire `sandbox-local`

`sandbox-local` runs the agent's code directly on the host, with no isolation.

```bash theme={null}
tai plugins install tai42-sandbox-local
```

* Name the `sandbox_module`, then set `SANDBOX_LOCAL_ROOT` to the host workspace
  root. A persistent session lives at `<SANDBOX_LOCAL_ROOT>/<workspace_key>`.
* It provides isolation `none` **only** and rejects a `container` or `vm`
  isolation floor. A deployment that keeps the default
  `sandbox_isolation="container"` must lower the floor to `none` to run under it.

> [!WARNING]
>
> `sandbox-local` runs the code on the host with no isolation. The code holds the
> credentials the operator injects into the session and, under the default open
> egress, reaches the full host network. Lower `sandbox_isolation` to `none`
> deliberately, and tighten `sandbox_egress` if the workload does not need the
> internet.

> [!NOTE]
>
> Both agents' `session_image` settings stay required and digest-validated under
> `sandbox-local`, but they are **inert**: the host is the environment, so the
> value is only recorded in session labels and never pulled. Any well-formed
> `...@sha256:` digest reference satisfies them — for example the published image's
> own digest, even though it is never used.

### Running `claude_code` direct-on-host

Running `claude_code` under `sandbox-local` requires the **operator** to install
the Claude runtime on the host first — the `claude-agent-sdk` wheel (it bundles
the Claude Code CLI, no separate Node.js) — because the shipped server image
stays lean and only the container sandbox carries the runtime out of the box.
`langchain_deep_agent` needs no extra runtime direct-on-host. Under
`sandbox-docker` both agents run from the pinned session image with nothing extra
to install.

## The engine under Compose and Kubernetes

Under Compose the engine is opt-in: the `profiles: ["sandbox"]` engine on a
`sandbox-ctrl` control network. A session is an **inner** container of the
rootless-dind daemon — NAT'd out for internet egress only, never on the
deployment network, and unable to address serve, the backend, the datastores, or
the engine itself.

On Kubernetes, run the engine as its own workload (its privilege isolated to
the engine pod, the app pod untouched) or point the provider at an external
endpoint.

## Durability

An ephemeral session's scratch dies with it. A persistent session binds the
durable `tai-sbx-<workspace_key>` volume.

> [!WARNING]
>
> A persistent session needs real, node-independent block storage from the
> distribution layer — a PVC on Kubernetes, a named volume in Compose. Without it,
> a session's data does not survive a node move.

## Security posture

> [!WARNING]
>
> The engine control endpoint is code-execution authority. Keep it behind mTLS,
> never bare.

> [!WARNING]
>
> Egress defaults **open**, so tool-result data is exfiltratable under it. The
> hardening path — a tighter `network` level plus an Anthropic-only proxy — is
> offered, not forced. An in-session model credential lives for the session
> lifetime.

> [!NOTE]
>
> Set `SANDBOX_DOCKER_READINESS_PROBE_ENABLED` to have the provider PROVE, on every
> session create, that the engine's egress firewall is in force before it returns a
> session — a throwaway probe container on the egress tier that must not reach the
> engine control address and must reach its own resolver — and refuse the create
> loudly when it cannot. It is defense in depth for the window an engine restart opens
> under a running app; the engine's own healthcheck-gated start order remains the
> primary guarantee. See the `sandbox-docker` plugin page for the
> `SANDBOX_DOCKER_READINESS_*` settings.

> [!NOTE]
>
> The platform tools an agent uses are adapter-proxied: the agent uses exactly the
> `tool_names` the caller grants, executed under the run's own identity, with no
> credential or MCP endpoint exposed to the session. There is no scoped mount or key
> to configure for them. (The `sandbox_exec` contrast — code that runs **inside**
> the session with the injected credentials — is on the
> [sandbox concept page](/concepts/sandbox#running-code-as-a-named-tool).)

## See also

* [Sandbox](/concepts/sandbox) — the contract, isolation floor, and durability
  model.
* [Use the ready-made agents](/guides/use-the-ready-made-agents) — `claude_code`
  and `langchain_deep_agent`, the shipped sandbox-driving agents.
* [Plugins](/plugins) — the `sandbox-docker` and `sandbox-local` plugin pages and
  their full engine setup.


# Storage providers
Source: https://docs.tai42.ai/operate/storage

Back the ResourceManager with the local filesystem, S3, or a GitHub repository.

A storage provider is where [stored content](/concepts/storage-and-resources)
lives: templates, uploaded files, and anything the ResourceManager reads or
writes. One provider is active per server, named by `storage_module` in the
manifest.

| Provider | Package | Backing store | When to pick it |
| - | - | - | - |
| local | `tai42-storage-local` | A directory on the server's own disk. | A single-process install. |
| s3 | `tai42-storage-s3` | Any S3-compatible bucket, including MinIO. | A multi-replica fleet, or durable shared object storage. |
| github | `tai42-storage-github` | A branch of a GitHub repository. | Every write should be a reviewable commit. |

> [!WARNING]
>
> Local storage is per-process state on one machine's disk. A multi-replica fleet
> gives each replica its own copy — use S3 or GitHub instead.

## Install and configure one

Each provider's package, its `storage_module` manifest key, its `STORAGE_<KIND>_*`
settings, and its store-specific setup (S3 bucket policy and MinIO addressing,
GitHub token scopes and the 1 MiB / CDN-staleness limits) live on the plugin
page:

> **[storage-local](/plugins/tai42/storage-local)**
>
> `STORAGE_LOCAL_*` — a root directory on local disk, required: every call refuses until it is set.

> **[storage-s3](/plugins/tai42/storage-s3)**
>
> `STORAGE_S3_*`, the bucket policy, and MinIO.

> **[storage-github](/plugins/tai42/storage-github)**
>
> `STORAGE_GITHUB_*`, token scopes, and the write/read caveats.

## Inbound media

When a participant sends a file over the [conversation
bridge](/reference/conversation-bridge) — a photo, document, voice or audio clip,
or video — the platform fetches the bytes, verifies them, and stores them by
reference through the active storage provider, then serves them back from a
same-origin capability URL that carries an unguessable id. Ingestion therefore
needs a registered storage provider (any of the three above). The default
self-hosted image bakes and selects `storage-local`, so inbound media works out
of the box; register no provider and an inbound file is rejected loudly — the
sender is told "That attachment could not be received." (or the route's
`reply_texts.rejected_could_not_receive`) — rather than dropped in silence.

Per-kind size ceilings are `MEDIA_INGEST_*` settings —
`MEDIA_INGEST_MAX_IMAGE_BYTES` (8 MiB), `MEDIA_INGEST_MAX_AUDIO_BYTES` (16 MiB),
`MEDIA_INGEST_MAX_VIDEO_BYTES` (25 MiB), and `MEDIA_INGEST_MAX_DOCUMENT_BYTES`
(25 MiB) by default; the [settings reference](/reference/settings) carries every
`MEDIA_INGEST_*` variable and its value. Which files are accepted depends on their
kind: photos, audio, and video are stored only when their bytes carry a recognised
signature that matches an allowlisted type — a file that merely claims to be an
image is rejected — while documents of text-like allowlisted types (such as plain
text or CSV) are accepted by their declared type and are always served as a
download, never as active content. Active content such as SVG, HTML, or JavaScript
is on no allowlist and is never accepted.

A stored inbound file is retained for the life of its conversation record (30 days
by default): the platform records each file's expiry in a durable index and a
background reaper walks that index to delete past-horizon files, so nothing is
held forever — a file that outlives its own record is still reaped.

## See also

* [Storage and resources](/concepts/storage-and-resources) — the ResourceManager contract.
* [Manage stored content](/guides/manage-stored-content) — the day-to-day commands.


# Deploying the Studio
Source: https://docs.tai42.ai/operate/studio

Serve the built Studio app from the skeleton, with the import map and OAuth-bridge notes.

The Studio ships as a static single-page app that the skeleton serves. There is
no separate Studio server to run: you point the skeleton at the built app, and
it hosts the UI on the same origin as the `/api/*` surface the UI drives.

## Serve the built app

Build the Studio to a `dist` directory, then set the skeleton's
`STUDIO_DIST_PATH` (the `studio_dist_path` setting) to that path and start the
server. The skeleton serves the app — `index.html`, the hashed asset bundles,
and the stable `vendor/` modules — under its own origin, with the `/api/*`
routes taking precedence and every other path falling back to the app shell.

```bash theme={null}
export STUDIO_DIST_PATH=/path/to/studio/dist
tai serve --manifest-path manifest.yml
```

![The Studio served by a skeleton.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/tools-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=0bee7e0b59692ae790dfb52b2f0c39ec)

The Studio, served by the skeleton on the same origin as its API.

> [!NOTE]
>
> `studio_dist_path` is a per-deployment setting, not [manifest](/concepts/manifest)
> content. Leave it unset on a server that does not host the UI — the app route
> answers `404` while the path is unset.

## Deep links under access control

With access control on, a refresh or bookmark of an inner Studio route — `/agents`,
`/settings`, and the rest — serves the dataless SPA shell, not a `404`, so **deep
links work without pinning `/` or any SPA path public**: you never add the app
routes or asset prefixes to the public-route table. The
[Studio SPA shell](/concepts/access-control#the-studio-spa-shell-is-public-its-data-is-not)
concept covers why the shell leaks nothing and what stays behind `/api/*`.

> [!NOTE]
>
> A headless / API-only deployment that hosts no UI can turn the fallback off by
> setting `spa_shell_public` to `false`. A genuinely public non-`/api` GET route
> outside the shell must instead be listed in `acknowledged_public_routes`, which
> the boot audits explicitly.

## Why the app must be built and served

The skeleton injects an import map into `index.html` at serve time — the map
that resolves the app's shared modules (`react`, `@tai42/studio-sdk`, and the
rest) and, for a [Studio plugin](/reference/studio-sdk/index), the plugin's
bundle. A statically previewed `index.html` carries the un-replaced import-map
anchor and dies on the first bare import, so a Studio plugin loads only against
a built app the skeleton serves — never under a plain dev server.

## The OAuth-bridge allowlist

[Connectors](/concepts/connectors) that use OAuth redirect through the skeleton,
or through its configured OAuth bridge. When `CONNECTORS_OAUTH_BRIDGE_URL` is set
on the skeleton, the bridge origin **must** also appear in the skeleton's
`CONNECTORS_REDIRECT_URI_ALLOWLIST`.

> [!WARNING]
>
> If the bridge origin is missing from `CONNECTORS_REDIRECT_URI_ALLOWLIST`, every
> Connect flow fails closed — the skeleton rejects the redirect and no connector
> can be authorized.

See the [deploy guide](/operate/deploy) for running a server for real, the
[serve command](/reference/cli/serve) for the launch flags, and the
[Studio SDK reference](/reference/studio-sdk/index) for building a Studio plugin.


# Publish a connector without code
Source: https://docs.tai42.ai/plugins/authoring-descriptor-plugins

Scaffold, fill, and publish a descriptor-only plugin — a whole OAuth connector as one tai-plugin.yml, no Python package.

A [connector](/concepts/connectors) is data, not code: its whole definition is a
[`ProviderDescriptor`](/reference/python-sdk/contract-connectors) — the provider's
OAuth endpoints, its sub-services and scopes, and the env var names that hold the
operator's client credentials. So a connector ships as a **descriptor-only
plugin**: a `tai-plugin.yml` with no `package`, [delivered by
`spec`](/concepts/marketplace#delivery-package-or-descriptor). There is nothing to
build and nothing to pip-install — publishing the descriptor publishes the whole
integration.

This page walks the path end to end. For the file-format rules your docs follow,
see [Author plugin docs](/marketplace/authoring-docs); for the model behind the
descriptor, see the [ProviderDescriptor
reference](/reference/python-sdk/contract-connectors).

## Scaffold the plugin

`tai plugins init` writes a valid, ready-to-edit descriptor tree. A connector needs
`--auth` — `oauth` for an OAuth provider, `none` for a no-auth one:

```bash theme={null}
tai plugins init connector-acme --kind connector --auth oauth
```

The written tree parses as a plugin spec and its docs validate as-is, so you edit
placeholders rather than start from a blank file. Print the full schema of a
`tai-plugin.yml` anytime with:

```bash theme={null}
tai plugins schema
```

## Fill the descriptor

Open `tai-plugin.yml` and replace every placeholder — the `acme` identifiers, the
`example.invalid` endpoints, and the icon — with your provider's real values:

```yaml tai-plugin.yml theme={null}
spec_version: 1
namespace: acme            # your marketplace namespace (never tai42)
name: connector-acme
version: 0.1.0
display_name: Acme
description: OAuth connector provider for Acme.
icon: https://cdn.acme.example/icon.png
license: Apache-2.0
repository: https://github.com/acme/connector-acme
contract: '>=10.0,<11'
categories: [connectors]
provides:
  - kind: connector
    # The connector item name MUST equal provider.id below — it is the manifest
    # and uninstall key. Rename both together.
    name: acme
    description: OAuth connector for Acme.
    provider:
      id: acme
      kind: oauth
      origin: community      # 'system' is reserved for the tai42 namespace
      category: communication
      display_name: Acme
      description: Connect your Acme account.
      icon_url: https://cdn.acme.example/icon.png
      oauth:
        authorize: https://acme.example/oauth/authorize
        token: https://acme.example/oauth/token
        revoke: https://acme.example/oauth/revoke
      # The operator sets these to their OWN OAuth client credentials at install;
      # the client secret is masked automatically.
      client_id_env: CONNECTORS_ACME_CLIENT_ID
      client_secret_env: CONNECTORS_ACME_CLIENT_SECRET
      sub_services:
        acme:
          id: acme
          display_name: Acme
          description: Acme on its hosted MCP server.
          scopes: [https://acme.example/auth/acme.readonly]
          mcp_server:
            type: http
            url: https://acme.example/mcp
```

A few rules the model enforces, loud on validation:

* **No `package`.** Omitting it is what makes the plugin descriptor-only. Its
  `delivery` derives to `descriptor`, and installing it touches no environment
  beyond the config it declares.
* **`icon` and `icon_url` are `https://` URLs.** The catalog serves the brand mark
  verbatim; there is no bundled asset to host, and a non-https URL is refused.
* **`origin` matches the namespace.** A `tai42` listing may claim `system`; every
  community listing is `community`.
* **The connector item `name` equals `provider.id`.** That id is the manifest key
  the install patches into the server's `connectors` list.

Then write the operator notes in `docs/index.mdx` — what OAuth client the operator
registers with the provider, which scopes it needs, and the redirect URI to
configure. Keep it a thin provider page; link platform features to their central
docs rather than re-documenting them.

## Publish

**1. Open a pull request**

Commit the filled tree to the plugin's repository and open a PR. The same docs
contract the marketplace enforces runs in CI, so a page that would fail ingest
fails the PR first.

**2. Tag the release**

Tag the version to match `tai-plugin.yml` (and `version.txt`, which exists only
so release tooling has a version file to read). The marketplace resolves a
descriptor listing by its `<namespace>-<name>` tag component.

**3. Seed the listing**

The marketplace ingests the tag: for a descriptor it fetches the raw
`tai-plugin.yml` at that tag, records its digest, and lists it with
`source: spec` — no wheel, no PyPI lookup. The listing and its `docs/` render
under [Plugins](/plugins) automatically; you never open a PR against the docs
site.

Once listed, an operator installs it like any plugin — supplying their own client
credentials — and the server registers the descriptor with no code on the box:

```bash theme={null}
tai plugins install acme/connector-acme \
  --env CONNECTORS_ACME_CLIENT_ID=... \
  --env CONNECTORS_ACME_CLIENT_SECRET=... \
  --secret CONNECTORS_ACME_CLIENT_SECRET
```

`--env KEY=VALUE` supplies every value; `--secret KEY` is a bare mark that hides
one (the server also auto-marks the connector's `client_secret_env`).

See [Installing a descriptor-only
plugin](/concepts/marketplace#installing-a-descriptor-only-plugin) for what the
server does with it.

## Checklist

`tai plugins init` scaffolds every file below; confirm each is filled before you
tag:

* [ ] **`tai-plugin.yml`** — no `package`; real `namespace`/`name`/`version`,
  provider endpoints, scopes, and `client_*_env` names.
* [ ] **`README.md`** — the repository's own front page.
* [ ] **`docs/index.mdx`** — the operator setup notes rendered under
  [Plugins](/plugins); front matter is exactly `title` and `description`.
* [ ] **`icon.png`** — the brand-mark image committed in the repo AND published at
  a raw `https://` URL; `icon` and `icon_url` both point at that https URL
  (http, relative, or empty is rejected).
* [ ] **`version.txt`** — equals the `version` in `tai-plugin.yml`.
* [ ] **`CHANGELOG.md`** — Keep-a-Changelog format.
* [ ] **`LICENSE`** — the plugin's license.
* [ ] **`NOTICE`** — attributions, including the source of the icon brand mark.

## See also

* [Connectors](/concepts/connectors) — the engine a descriptor plugs into.
* [The marketplace](/concepts/marketplace#delivery-package-or-descriptor) — the package/descriptor delivery axis.
* [Author plugin docs](/marketplace/authoring-docs) — the docs contract every listing follows.
* [ProviderDescriptor reference](/reference/python-sdk/contract-connectors) — the full descriptor schema.


# Plugins
Source: https://docs.tai42.ai/plugins/index

Every plugin listed on the marketplace, grouped by what it provides.

Every listed plugin, grouped by what its first item provides — 29 across 10 groups. Each plugin page carries its install line, declared permissions, the items it provides, and the author's own documentation.

> **Tools**
>
> 5 plugins.

> **Identity**
>
> 2 plugins.

> **Agents**
>
> 1 plugin.

> **Backends**
>
> 3 plugins.

> **Sandboxes**
>
> 2 plugins.

> **Channels**
>
> 5 plugins.

> **Monitoring**
>
> 1 plugin.

> **Storage**
>
> 3 plugins.

> **Webhook verifiers**
>
> 2 plugins.

> **Connect outside systems**
>
> 5 plugins.


# accounts-postgres
Source: https://docs.tai42.ai/plugins/tai42/accounts-postgres

Postgres-backed accounts provider for the TAI ecosystem: an installable plugin that owns user accounts, password login, sessions, and invites, and registers itself as the "accounts-postgres" provider.

> [!NOTE]
>
> `Identity` plugin · listing `tai42/accounts-postgres`

## Install

```bash theme={null}
tai plugins install tai42-accounts-postgres
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | no |

## Provides

### accounts-postgres

`Identity` — Postgres-backed accounts/identity provider — owns user accounts, password login, sessions, and invites.

### login

`Router` — The public /api/login/\* routes.

### users

`Router` — The authed /api/auth/users/me/password self-service password route.

Provides human logins on Postgres — an email and password, a session, and a role.
Member administration is the Studio's own generic Members page over the provider's
declared member actions, so this plugin ships no Studio page of its own. The account
model itself stays central; see [Accounts](/concepts/accounts). This page wires the
provider and its two routers.

## accounts-postgres

The identity provider. Mount it with both routers and register it as an auth
provider:

```yaml manifest.yml theme={null}
lifecycle_modules:
  - tai42_accounts_postgres
routers_modules:
  - tai42_accounts_postgres.routes_login
  - tai42_accounts_postgres.routes_users
```

```bash theme={null}
ACCESS_CONTROL_ENABLE=true
ACCESS_CONTROL_AUTH_PROVIDERS=["accounts-postgres","redis"]
```

Mounting the routes without registering the provider raises at boot, naming both
settings — the two halves are never half-wired.

### Connect the database

The provider carries no connection of its own. It binds to a named database through
`TAI_DB_BINDING_TAI42_ACCOUNTS_POSTGRES` (default `default`) and uses that database's
connection, keeping its own tables inside it. A single-database deployment leaves the
binding unset and configures `TAI_DATABASE_DEFAULT_PG_*`; give accounts its own
database by binding it to another declared name and configuring that one:

```bash theme={null}
# accounts on the default database
TAI_DATABASE_DEFAULT_PG_HOST=localhost
TAI_DATABASE_DEFAULT_PG_PORT=5432
TAI_DATABASE_DEFAULT_PG_DB=tai
TAI_DATABASE_DEFAULT_PG_USER=postgres
TAI_DATABASE_DEFAULT_PG_PASSWORD=...

# or accounts on its own database
TAI_DB_BINDING_TAI42_ACCOUNTS_POSTGRES=accounts
TAI_DATABASE_ACCOUNTS_PG_HOST=...
TAI_DATABASE_ACCOUNTS_PG_PASSWORD=...
```

The provider is on when its bound database is configured — a non-empty password — and
cleanly off otherwise. Pool sizes and timeouts are tuned on the database itself
(`TAI_DATABASE_<NAME>_PG_*`), not a variable of this package's own. Sessions live in
Postgres. The login throttle's counters (per-account backoff and per-IP failures) live
in Redis, on the plugin's own connection: `TAI_ACCOUNTS_REDIS_URL`, falling back to
`TAI_DEFAULT_REDIS_URL`. A login with no reachable Redis fails closed.

### Run the migrations

The plugin ships a `migrations/` folder and declares it in its descriptor, so the
shared runner discovers it as the `tai42-accounts-postgres` component and applies it
alongside the core chain:

```bash theme={null}
tai db migrate
```

The provider asserts its chain at boot and never applies it for you: with the store
configured but the chain pending, the process refuses to start, naming `tai db
migrate`.

### Tune sessions and login limits

| Variable | Default | Effect |
| - | - | - |
| `TAI_ACCOUNTS_SESSION_IDLE_SECONDS` | `86400` | Sliding idle timeout. |
| `TAI_ACCOUNTS_SESSION_ABSOLUTE_SECONDS` | `2592000` | Hard lifetime from mint. |
| `TAI_ACCOUNTS_INVITE_TTL_SECONDS` | `259200` | Invite validity. |
| `TAI_ACCOUNTS_LOGIN_BACKOFF_THRESHOLD` | `5` | Consecutive per-account failures before backoff. |
| `TAI_ACCOUNTS_LOGIN_BACKOFF_CAP_SECONDS` | `900` | Longest backoff lock. |
| `TAI_ACCOUNTS_LOGIN_IP_MAX_ATTEMPTS` | `30` | Failures allowed per IP per window. |
| `TAI_ACCOUNTS_LOGIN_IP_WINDOW_SECONDS` | `900` | Length of that window. |
| `TAI_ACCOUNTS_LOGIN_HASH_CONCURRENCY` | twice the CPU count, floor 2 | Concurrent password hashes before login sheds load. |
| `TAI_ACCOUNTS_LOGIN_HASH_WAIT_SECONDS` | `2.0` | Wait before shedding. |
| `TAI_ACCOUNTS_REDIS_URL` | unset | Redis holding the login-throttle counters. Falls back to `TAI_DEFAULT_REDIS_URL`; with the provider on, one must be set. |
| `TAI_ACCOUNTS_REDIS_KEY_PREFIX` | the database name | Redis namespace for the login-throttle counters. |

## login

The public `/api/login/*` routes: `POST /api/login/password` verifies an email and
password and mints a session, and `POST /api/login/invite/accept` sets a first password
from an invite. Passwords are at least ten characters.

The first owner is not created here. The platform's one-step setup door creates the
owner principal and, when this provider is configured, attaches the owner's login
through it — a password set now, or an invite link the owner follows later to set one.
The provider implements that attachment seam and owns no separate first-owner route.

## users

`PUT /api/auth/users/me/password` is the one route this module carries: a signed-in
person changing their OWN password, which revokes every other session. It is
self-service, not member administration, so it is open to every user, not just an admin.

Member administration is not routes here. The provider **declares** its member actions —
invite a user, send a new login link, cancel an invitation, change a member's role or
access, and remove a member — through the platform's generic member-actions seam, and
the Studio's own generic Members page renders them. There is no outbound email: inviting
a user (or sending a new link) returns a one-time invite token and a `/login?invite=...`
path relative to your origin (the deployment's declared login page and invite key,
`HOSTED_UI_LOGIN_PATH` and `HOSTED_UI_INVITE_QUERY_KEY`), shown once on the action's result; the invitee sets a
password through `POST /api/login/invite/accept`, which consumes the token and mints a
session in one step. `role` names an existing access-control role template; an unknown
name is rejected and no user is created. A member's role is read from the platform —
the role their principal holds, or **No role** when their access was not set from a
role. The platform refuses a change that would leave no enabled admin principal, and
every admin principal counts, not only accounts; see
[the last enabled admin stays](/concepts/permissions#the-last-enabled-admin-stays).

### Login throttles behind a proxy

The per-IP login counters key on the client the platform resolves for every public
door: the direct peer unless you declare your proxies with
`TAI_RATE_LIMIT_TRUSTED_PROXIES` or `TAI_RATE_LIMIT_TRUSTED_HOPS`, in which case the
forwarded client. An IPv6 client is counted by its `/64`. See
[which client a request is from](/concepts/access-control#which-client-a-request-is-from).

## See also

* [Accounts](/concepts/accounts) — the model behind these routes.
* [Access control](/concepts/access-control) — the policy every identity resolves to.


# agents
Source: https://docs.tai42.ai/plugins/tai42/agents

Ready-made agents for the TAI ecosystem — coding/deep agents, tool-calling, retrieval, voting, refinement, and vision agents — opt-in and manifest-loaded.

> [!NOTE]
>
> `Agent` plugin · listing `tai42/agents`

## Install

```bash theme={null}
tai plugins install tai42-agents
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | yes |

## Provides

### langchain\_deep\_agent

`Agent` — Run a deep agent with planning, subagents, skills, and a filesystem backend.

### claude\_code

`Agent` — Run Claude Code inside a sandbox: it drives the real claude binary over a versioned exec protocol, with tools, skills, and subagents.

### refine\_agent

`Agent` — Run an Evaluator-Critic refinement loop until the Critic approves or the budget runs out.

### voting\_agent

`Agent` — Run a voting workflow — voter LLMs answer in parallel, then a judge LLM decides.

### retrieval\_tools\_agent

`Agent` · group `tools-agents` — A tools agent that retrieves its tools on demand from a vector store.

### tools\_agent

`Agent` · group `tools-agents` — Run a LangGraph tools agent over tools loaded by name (and optional presets).

### vqa\_agent

`Agent` — Analyze an image and answer a query about it using a multimodal LLM.

Ready-made agent workflows, each loaded by name into a manifest's
`agents_modules`. The model behind them, how to run one, and how to compose them
live in the central docs linked below; this page is the per-agent index and the
shared limits.

## Configuration

Limits shared by every agent in this package:

| Variable | Default | Effect |
| - | - | - |
| `TAI_AGENTS_MAX_VOTERS` | `16` | Hard ceiling on the voters one voting call may fan out to; an over-limit call raises before any voter runs. |
| `TAI_AGENTS_VOTER_CONCURRENCY` | `8` | Voters run concurrently within one voting call; the rest queue behind a semaphore. |
| `TAI_AGENTS_EMBEDDING_DIMS_CACHE_SIZE` | `64` | Bound on the retrieval agent's embedding-dims probe cache (an LRU). |
| `TAI_AGENTS_DEFAULT_RECURSION_LIMIT` | `50` | Default LangGraph `recursion_limit` when a run pins none; a caller-supplied limit wins. |
| `TAI_AGENTS_SYSTEM_PROMPT_CACHE_DEFAULT` | `true` | Mark the per-run system prompt for prompt caching on providers that support it (see [System-prompt caching](#system-prompt-caching)). |
| `TAI_AGENTS_STRUCTURED_OUTPUT_REPROMPT_CAP` | `3` | How many times a run re-prompts a model whose final answer fails to parse or validate against a requested `response_format`, or carries no structured answer, before it ends with a typed outcome (see [Structured-output outcomes](#structured-output-outcomes)). |
| `TAI_AGENTS_GRAPH_CACHE_SIZE` | `64` | How many compiled tools-agent graphs each event loop keeps for reuse (an LRU); a tool registration change or a settings reload makes the next run compile afresh. |
| `TAI_AGENTS_CHAINED_PARK_HORIZON_CAP_HOURS` | `168` | Ceiling, in hours, on how far ahead a chained park (one waiting on a nested call) may keep its inherited deadline. The park's horizon is the nearest of the inherited deadline, this cap and the run's own retention bound; a nested run with no deadline takes the cap. |

### Structured-output outcomes

When a run requests a `response_format`, the model's answer is forced through a
rail that re-prompts the model each time its final answer fails to parse or
validate against the schema, or carries no structured answer at all (an empty
reply, or the answer written as plain text instead of the structured output). A
turn in which the model only calls other tools is not judged; the run continues,
also when those calls all failed to parse (see [Tool-error
resilience](#tool-error-resilience)). A structured answer whose arguments do not
parse is judged even when the same turn also calls other tools. Two typed, **non-fatal** terminal outcomes bound that loop, so
a run that cannot produce a conforming or bounded answer ends readably instead of
failing generically. Each surfaces exactly like a normal terminal — the streaming
faces emit it as a terminal event, `run` returns it as the run's value, the agent
run route emits it as one SSE frame, and a conversation route surfaces it to the
turn's reply — so a flow or route branches on its `type`:

| Outcome (`type`) | Raised when | Fields |
| - | - | - |
| `structured_output_unresolved_final` | The model never produced schema-conforming output within `TAI_AGENTS_STRUCTURED_OUTPUT_REPROMPT_CAP` re-prompts. | `schema_name`, `attempts` (non-conforming responses, the cap plus the final rejected attempt), `error` (the last error, masked: a validation error, or the message naming the missing structured answer) |
| `recursion_limit_final` | The run hit its graph step ceiling (`recursion_limit`) before finishing. | `limit`, `steps` (known step count, else null) |

Both carry `final: true`. Neither raises — a branch that does not handle them
reads them as the run's terminal value.

### Async-park index

A park-capable run whose tool async-parks (`ask(mode="async")`) writes a durable
index that reverses a parked interaction id back to its parked run, so a later worker
can resume it. This needs the `[park]` extra (`pip install tai42-agents[park]`) and a
Redis URL:

| Variable | Default | Effect |
| - | - | - |
| `TAI_AGENTS_REDIS_URL` | falls back to `TAI_DEFAULT_REDIS_URL` | The agents plugin's Redis. It holds the park index and the workspace lease. With neither set there is no durable park index, so a park-capable run refuses the async ask loudly rather than parking where it cannot be resumed. The workspace lease serializes the turns of one `thread_id` across workers, so a threaded `claude_code` or `langchain_deep_agent` run needs this Redis even when it never parks; with neither set, such a run fails loudly when it takes the lease. A run with no `thread_id` takes no lease and does not touch Redis. |

The park index is the agents plugin's own Redis, independent of the checkpoint provider
and the interactions store. It is the platform kit's shared park index library
(`tai42_kit.interactions.park_index`) under the agents' own key namespace (`agent:park`);
the settings above are unchanged.

A parked run needs a durable checkpoint provider (`redis` or `postgres`), which keeps a
thread `LLM_PROVIDER_CHECKPOINT_RETENTION_WAITING_MINUTES` (default 7 days) after its last
write. The platform may still deliver an ask's answer up to its redelivery horizon
(`INTERACTIONS_IDLE_TTL_SECONDS`, default 1 day) after the ask's deadline, so every async ask
must carry a deadline at least that long before the checkpoint's retention runs out (with the
defaults, within 6 days): an ask with no deadline, or one past that point, is refused loudly
before anything is parked. While a park's barrier is live, the checkpoint sweep spares its
thread. A resume that finds the thread's checkpoint gone ends the run as a failed terminal.

A run with no `thread_id` mints its own thread and marks it finished when it ends without
a park, so the checkpoint sweep removes it
`LLM_PROVIDER_CHECKPOINT_RETENTION_FINISHED_MINUTES` (default 1 day) later. A
caller-supplied `thread_id` is the caller's: a run on it takes it out of the finished set
when it starts and never marks it.

When the ask is answered (or expires), the platform resumes the parked run and drives it
to its next outcome. The resumed run's final outcome is delivered by the **platform** to the
run's own address — the agent never delivers it itself; a caller that needs the answer runs
the agent through a door that receives it out of band (a conversation route). A kill takes
the whole run down — every open ask of the run, the runs nested under its calls and the callers
waiting on it; nothing of the run is resumed — and delivers a single terminal to that address: a deliberate
takedown (a cancel, a thread or route delete, a person erase) is delivered as `withdrawn`, so
the conversation says nothing to the person, and a lapsed `on_expiry="kill"` deadline is
delivered as a failed outcome.

A resumed run that **fails** — its graph raises, for example a model or provider error that
outlasts the model client's own retries — ends as a failed terminal instead of being retried:
an outermost run's address receives a failed outcome, and a run nested under another run (a
flow holding the agent, an agent calling it) reaches that caller as a **failure**, so the
caller's own error handling runs (a flow holder's `on_error`). The same holds when the
platform gives up on a park whose resume could not be driven at all within the redelivery
horizon: the caller the parked run was nested under is told it failed rather than waiting
out its own deadline.

An async ask may address the run's own **caller** (`ask(to="caller")`) instead of a human
(`to="user"`): the run parks the same way and resumes when the caller answers, so an agent
can hand a question back up to whatever invoked it. When an agent's own tool call drives a
nested run that async-parks, the agent parks on that **call** rather than blocking; once the
nested run reaches its terminal the agent's turn resumes with that terminal as the tool's
result, and a non-success terminal comes back as a model-visible tool error.

The parking agents (`tools_agent`, `langchain_deep_agent`, `claude_code`) set `parks = True`,
so the platform declares their run tools as tools that can pause; the hidden `agent_resume` and
`deliver_chained_park` tools declare it themselves (`meta={"tai42/pauses": True}`). A caller's
park recognition accepts the park they return. A tool an agent calls that returns a park signal
without that declaration fails the agent's run with `UndeclaredPauseError` naming the tool; the
model is not handed a tool error to retry around.

### Parking tools

An agent that lists the generic parking tools in its `tool_names` — `list_parked`,
`resume_parked`, `cancel_parked` — can list, answer, or cancel the caller asks parked on the
run's subject from inside its own turn. They are platform builtins and need no plugin code.

### Conversation-door tools

`send_conversation_message` and `send_conversation_event` let an agent reach a conversation
route from inside its own turn, in-process under the run's own execution identity — no route
key is handed to the agent. `send_conversation_message` posts a message into a route's
conversation; `send_conversation_event` delivers a structured event onto an existing thread
of one. Each applies the target door's own authorization before it runs and refuses a run
with no accountable execution identity loudly; the turn's answer is delivered by the route's
own configured delivery, never inline to the agent. List either in an agent's `tool_names`
to include it — they are platform builtins and need no plugin code.

## System-prompt caching

Every agent turn re-sends its whole system prompt. On a provider that takes a
system-prompt cache breakpoint, marking the prompt lets the provider cache that
stable prefix and read it back on later turns instead of re-billing it. This is
**on by default** (`TAI_AGENTS_SYSTEM_PROMPT_CACHE_DEFAULT=true`), server-wide; a
provider that caches without a mark, or does not support one, is left unmarked —
the mark form is the provider's own, so it is never named here.

Per node, the `tools_agent`'s `system_content_kwargs` overrides the default:
leave it unset to take the default, pass `{}` to opt this node out (no mark), or
pass an explicit mark to set your own. The other faces follow the server-wide
setting only.

Which faces carry it:

| Face | Marking |
| - | - |
| `tools_agent` (invoke + stream) | default at the shared build seam; per-node override via `system_content_kwargs` |
| `voting_agent` | inherits the default — its voters and judge run through the `tools_agent` build seam |
| `refine_agent` | default at each role's model build |
| `langchain_deep_agent` | default at the model build (the mark rides the deep agent's per-run system message) |
| `retrieval_tools_agent` | excluded — its graph prepends the system prompt into the message list it rolls to the newest breakpoint, so a system mark there is stripped by any later turn mark; use `user_content_kwargs` to mark the user turn |
| `claude_code` | not applicable — the system prompt is handed to the Agent SDK verbatim, never as a content block |

### Per-provider history shaping

Each provider answers two questions about the outgoing request, and every agent applies
the answers at the model call only — nothing is written to the stored thread:

* **A leading user turn.** When a history's first non-system message is an assistant turn
  (an operator opened the thread), a provider that requires a user turn first gets an inert
  `[conversation start]` user turn added to that one request.
* **A rolling cache breakpoint.** A provider that takes a per-block cache mark keeps only the
  newest marked block per request, so per-turn marking stays within the provider's per-request
  breakpoint cap.

## Final text

`run` and `astream` hand back the same final text: the reply text of the last message — its
plain text, or its text blocks joined with nothing between them. Thinking, reasoning, tool-use
and server-tool blocks are never part of it.

## Run keywords

Each agent's `run` and `astream` declare the keywords that agent reads — the platform's four
(`thread_id`, `user_message`, `tool_names`, `response_format`) plus the agent's own knobs, the
fields of its tool input. A keyword an agent does not declare is refused with a `TypeError`
naming it, never dropped; a platform key an agent cannot honor is refused with a `RuntimeError`
naming the reason (the voting and refine agents take role-named messages instead of
`user_message` and per-role configs instead of `thread_id`; the voting agent always produces
its `VotingOutput`; the vqa agent runs one completion with no tools and no thread).

| Agent | Keywords beyond the platform's four |
| - | - |
| `tools_agent` | `tools`, `presets`, `system_message`, `system_content_kwargs`, `user_content_kwargs`, `llm_provider`, `llm_kwargs`, `checkpoint_provider`, `resume`, `resume_checkpoint_id`, `recursion_limit`, `langgraph_config` |
| `langchain_deep_agent` | `tools`, `subagents`, `skills`, `inline_skills`, `system_message`, `interrupt_on`, `user_content_kwargs`, `resume`, `recursion_limit`, `llm_provider`, `checkpoint_provider`, `store_provider`, `llm_kwargs`, `langgraph_config` |
| `retrieval_tools_agent` | `tools`, `presets`, `system_message`, `embedding_provider`, `llm_provider`, `checkpoint_provider`, `store_provider`, `overwrite_store`, `tools_limit`, `embedding_kwargs`, `llm_kwargs`, `user_content_kwargs`, `resume_checkpoint_id`, `recursion_limit`, `langgraph_config` |
| `refine_agent` | `evaluator_message`, `critic_message`, `max_iterations`, `evaluator_llm_provider`, `critic_llm_provider`, `checkpoint_provider`, `evaluator_llm_kwargs`, `critic_llm_kwargs`, `evaluator_langgraph_config`, `critic_langgraph_config`, `user_content_kwargs` |
| `voting_agent` | `judge_tools`, `voter_tools`, `judge_message`, `voter_message`, `judge_llm_provider`, `checkpoint_provider`, `judge_llm_kwargs`, `voters`, `judge_langgraph_config`, `voter_langgraph_config`, `user_content_kwargs` |
| `vqa_agent` | `image_url`, `query`, `llm_provider`, `llm_kwargs` |
| `claude_code` | `system_message`, `skills`, `inline_skills`, `max_turns`, `subagents` |

Live in-process `tools` are the platform's framework-neutral `ClientTool` handles (from
`tai42_app.tools.get_client_tools`, or any object with `name`, `description`, `input_schema` and
an async `invoke`); this plugin adapts each to its LangChain runtime, and every tool name the model
is handed is held to the 64-character bound — a longer one is refused, never truncated. A preset is
handed under its own name, so a short-named preset over a longer-named base tool binds.

Each agent also reports the memory its run keywords address (`addressed_memory`): the thread and
checkpoint ids its `langgraph_config` (or per-role configs) and `resume_checkpoint_id` carry, and
the continuity keys (`resume`, `resume_checkpoint_id`, `checkpoint_provider`) it reads. The
platform refuses an id in its reserved `bridge:` namespace from that answer, and a conversation
route refuses a start that sets a continuity key.

## Session credentials

`claude_code` and `langchain_deep_agent` turn their operator `creds` list into what a
session receives by one rule:

| Entry | Resolved channel | Where it lands |
| - | - | - |
| `static` | its value | the session env, under its `env_name` |
| `connection` | the `env` channel | the session env, under its own names (either delivery) |
| `connection`, `delivery: env` | the access token | the session env, RAW, under the cred's `env_name` |
| `connection`, `delivery: bearer` | the access token and the headers | one credential-helper file named after the cred's `env_name`: `Authorization: Bearer <token>` then one `<Name>: <value>` line per header |

Refused loudly, naming the cred:

* `connection cred '<env_name>' resolved HTTP headers, which delivery='env' cannot carry; use delivery='bearer'`
* `required connection cred '<env_name>' resolved to no usable credential for the current caller (connection '<connection_id>')`

A non-required connection cred that resolves to nothing injects nothing. The session env is
fixed when the session is created: a persistent session keeps its create-time env until it is
recreated, while bearer files are re-written every turn.

## Tool-error resilience

A tool failure surfaces to the model as an error tool result and the agent loop
continues, rather than aborting the run: a `ToolException` — which is how an
in-process tool's own body exception is reported — or a pydantic `ValidationError`
from a malformed tool call becomes an error result the model can react to. Failures
outside the tool call (agent machinery, provider or infrastructure errors) still
abort loudly. This holds across every tool-running agent in this package, including a
deep agent's explicit and nested subagents. A tool call whose arguments did not parse
(the provider reports it as an invalid tool call) is answered right after the model
turn with an error result carrying the parse error, so the next request answers every
call the model made; the stream shows it as a tool call with no arguments followed by
that error result. A broken call that carries no call id or no tool name cannot be
answered, because a tool result needs both; it is logged as a warning. When every call
of a turn failed to parse and the turn produced no structured answer, the model is
called again to read the errors, and the run's recursion limit bounds those retries. A
broken call to the structured-output tool is judged by the structured-output rail
instead (see above). A thread whose previous turn was aborted mid-tool-call is repaired
at the next turn start — the calls of its last model turn that have no result yet,
valid or invalid, get synthetic error results so the provider accepts the thread —
while a thread paused on a real interrupt is left untouched.

## langchain\_deep\_agent

Runs a deep agent with planning, one level of nested subagents, skills,
human-in-the-loop interrupts (resumed with a LangGraph `Command`), and a per-thread
scratch filesystem.

### Sandbox requirement

The scratch filesystem **is** a durable [sandbox](/concepts/sandbox) backend over the
same `SandboxSession` contract, so a run requires a registered sandbox provider — with
none installed it fails loudly at `require_sandbox()`. Its working files persist and
reap under the operator's durability settings, so installing a sandbox provider is a
hard prerequisite, not an optional add-on.

### Structured output

A `response_format` is validated up front: the JSON Schema must carry a top-level
`title`, and every `oneOf` variant must carry a non-empty `title` of its own — a schema
missing either raises a `ValueError` before the run starts. When a run requests a
`response_format` but produces no structured output, **both faces raise rather than
silently omitting the structured frame**: the JSON `run` face raises on drain, and the
streaming face raises after the stream drains — unless the run paused on a pending
interrupt, which takes precedence over the missing-structured raise.

### Configuration (`TAI_AGENTS_LANGCHAIN_DEEP_*`)

| Variable | Default | Effect |
| - | - | - |
| `TAI_AGENTS_LANGCHAIN_DEEP_SESSION_IMAGE` | required | The scratch session image (python3 and coreutils) — a digest reference `…@sha256:<64 hex>`; a bare tag or an unset value is rejected at run start. |
| `TAI_AGENTS_LANGCHAIN_DEEP_CREDS` | empty | Session creds injected into the session shell (service creds only; the model call runs server-side, so no model credential enters the session). See [Session credentials](#session-credentials). |
| `TAI_AGENTS_LANGCHAIN_DEEP_SESSION_TTL_SECONDS` | `86400` | Workspace/session idle-reap deadline; also bounds how long a park may wait. |
| `TAI_AGENTS_LANGCHAIN_DEEP_NETWORK` | inherit | Narrows the platform egress posture (`none`/`internal`/`egress`); a value looser than the platform ceiling is refused at session create. |
| `TAI_AGENTS_LANGCHAIN_DEEP_CPU` | unset | Session CPU cap, enforced by the sandbox provider or refused by it. |
| `TAI_AGENTS_LANGCHAIN_DEEP_MEMORY_MB` | unset | Session memory cap in MB, enforced by the sandbox provider or refused by it. |
| `TAI_AGENTS_LANGCHAIN_DEEP_CRASH_RESUME` | `false` | Re-dispatch a recycled detached run at-least-once (re-executes from scratch). Recycle-class. |

## claude\_code

Runs Claude Code as a platform agent: it drives the real `claude` binary through the
Claude Agent SDK **inside a sandbox session** over a versioned exec protocol. The plugin
server never imports the SDK — the SDK lives in the session image, and only the runner
payload (shipped as data and executed in-session) imports it.

### Sandbox requirement

`claude_code` requires a registered sandbox provider. Install one, e.g.
`tai plugins install tai42-sandbox-docker`. A run on a box with no provider raises a loud
`SandboxUnavailableError` on every door. The session image is operator-configured and MUST
be a digest reference (a bare tag is rejected at run start).

### Configuration (`TAI_AGENTS_CLAUDE_*`)

| Variable | Default | Effect |
| - | - | - |
| `TAI_AGENTS_CLAUDE_API_KEY` | unset | The metered `ANTHROPIC_API_KEY` path. Set this XOR `OAUTH_TOKEN` — exactly one, or run start fails loudly. |
| `TAI_AGENTS_CLAUDE_OAUTH_TOKEN` | unset | The subscription `CLAUDE_CODE_OAUTH_TOKEN` path (from `claude setup-token`). Set this XOR `API_KEY`. |
| `TAI_AGENTS_CLAUDE_SESSION_IMAGE` | required | The claude session image — a digest reference `…@sha256:<64 hex>`; a bare tag is rejected. |
| `TAI_AGENTS_CLAUDE_HOOK_SETTINGS` | unset | A Claude Code hooks fragment materialized verbatim into the adapter-authored `.claude/settings.json`. Executable configuration — operator-scoped, never a caller field. |
| `TAI_AGENTS_CLAUDE_MODEL` | SDK default | Model pin; production deployments should pin. |
| `TAI_AGENTS_CLAUDE_MAX_TURNS` | `100` | Per-run turn ceiling. |
| `TAI_AGENTS_CLAUDE_MAX_BUDGET_USD` | unset | Per-run cost ceiling. |
| `TAI_AGENTS_CLAUDE_RUN_TIMEOUT_SECONDS` | `3600` | Wall-clock ceiling for one drive; the exec times out loudly on expiry. Set ≥ the platform turn budget. |
| `TAI_AGENTS_CLAUDE_SESSION_TTL_SECONDS` | `86400` | Workspace/session idle-reap deadline. |
| `TAI_AGENTS_CLAUDE_NETWORK` | inherit | Narrows the platform egress posture (`none`/`internal`/`egress`); a value looser than the platform ceiling is refused at session create. |
| `TAI_AGENTS_CLAUDE_CRASH_RESUME` | `false` | Re-dispatch a recycled detached run at-least-once (re-executes from scratch). Recycle-class. |

Session creds (`TAI_AGENTS_CLAUDE_CREDS`) are a list of static values or per-caller
connection references injected into a CLEAN session env or a per-turn bearer
credential-helper file — never the host env. A connection-reference cred resolves per-caller
and fails closed on a door with no bound execution identity. See
[Session credentials](#session-credentials) for the one rule both sandbox agents apply.

**Adapter-proxied platform tools.** Granted `tool_names` run under the run's own execution
identity through the same `run_tool` seam every agent uses — the session reaches no
platform network surface and holds no key or MCP endpoint. The model sees each granted tool
with its own description and argument schema. A non-empty `tool_names` on a
door with no bound execution identity is refused loudly (fail-closed).

**Stated residual (security is configuration).** The one injected model credential lives in
the session env, so the session's own Bash can read it and it can reach the persisted
transcript. The credential scrub removes credential FILES on a terminal exit; when the
platform `sandbox_scrub_transcript` flag is on, injected credential VALUES are also redacted
from the kept transcript.

Async `ask` parks are supported on threaded (conversation) runs and use the same
`[park]` extra + `TAI_AGENTS_REDIS_URL` as the other parking agents (see
[Async-park index](#async-park-index)); an async ask on a thread-less tool-face run is
refused loudly (its ephemeral workspace could never be resumed).

## refine\_agent

Runs an Evaluator-Critic refinement loop until the Critic approves or the budget runs
out.

## voting\_agent

Runs a voting workflow — voter LLMs answer in parallel, then a judge LLM decides.
Bounded by `TAI_AGENTS_MAX_VOTERS` and `TAI_AGENTS_VOTER_CONCURRENCY`.

## retrieval\_tools\_agent

A tools agent that retrieves its tools on demand from a vector store.

## tools\_agent

Runs a LangGraph tools agent over tools loaded by name (and optional presets). A tool
that async-parks (`ask(mode="async")`) suspends the run instead of blocking; it
resumes on a later worker when the ask is answered or expires. This needs the `[park]`
extra and `TAI_AGENTS_REDIS_URL` (see [Async-park index](#async-park-index)).

## vqa\_agent

Analyzes an image and answers a query about it using a multimodal LLM.

## See also

* [Agents](/concepts/agents) and [Deep agents](/concepts/deep-agents) — the model.
* [Use the ready-made agents](/guides/use-the-ready-made-agents) — running each of these.
* [Author an agent](/guides/author-an-agent) — building your own.


# backend-arq
Source: https://docs.tai42.ai/plugins/tai42/backend-arq

arq execution backend for the TAI ecosystem — worker runtime and Redis-hash scheduling over arq.

> [!NOTE]
>
> `Backend` plugin · listing `tai42/backend-arq`

## Install

```bash theme={null}
tai plugins install tai42-backend-arq
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | yes |
| Filesystem | no |

## Provides

### arq

`Backend` — arq execution backend — background tool runs and schedules over Redis.

The arq backend runs queued tool calls, schedules, and agent turns over a single
Redis — no separate broker. It is the default the distribution bundle selects.

## Enable it

```yaml manifest.yml theme={null}
backend_module: tai42_backend_arq
```

A config that registers a task backend also needs the worker bus and a shared
hooks registry: `tai serve`, `tai backend`, a config reload and a config write all
refuse it unless `TAI_BUS_REDIS_URL` and `HOOKS_REDIS_URL` are set (each falls back
to `TAI_DEFAULT_REDIS_URL`). The backend process matches the events it raises
against its own hooks registry, so an in-memory one would run none of the hooks
registered through the server.

## Configuration

The `ARQ_` env group. `ARQ_REDIS_URL` and `ARQ_REDIS_MAX_CONNECTIONS` fall back
to the shared `TAI_DEFAULT_REDIS_URL` / `TAI_DEFAULT_REDIS_MAX_CONNECTIONS`
namespace when unset; a set `ARQ_` value always wins.

| Variable | Default | Effect |
| - | - | - |
| `ARQ_REDIS_URL` | `redis://localhost:6379/0` | Queue, results, and the schedule hashes. |
| `ARQ_REDIS_MAX_CONNECTIONS` | unset | Caps the arq connection pool; uncapped when unset. |
| `ARQ_RETRY_ATTEMPTS` | `0` | Times a failed Redis connect or command is retried, each retry logged as a warning; `0` makes one attempt. |
| `ARQ_RETRY_ON_TIMEOUT` | `false` | With `ARQ_RETRY_ATTEMPTS` at `0`, retries a timed-out command once at once. |
| `ARQ_SOCKET_TIMEOUT` | unset | Seconds a Redis command may wait on its socket; redis-py's default when unset. |
| `ARQ_SOCKET_CONNECT_TIMEOUT` | `1` | Seconds a Redis connect may take. |
| `ARQ_CALLBACK_TIMEOUT` | `5` | Seconds a callback job waits for its predecessor to complete. |
| `ARQ_JOB_COMPLETION_WAIT` | `300` | Seconds a graceful SIGTERM lets in-flight jobs finish before the worker exits (the warm drain). |
| `ARQ_TASK_TIMEOUT` | `300` | The dispatch job budget in seconds: the longest a job may run on the worker (the `--job-timeout` default), and how long a synchronous dispatch waits for a job result. |
| `ARQ_MANIFEST_KEY` | `MANIFEST_KEY` | Env var the host exports the live manifest JSON under. |
| `ARQ_TOOL_NAME_ARG` | `backend_tool_name` | Kwargs key carrying the target tool name into a queued job. |

## Run the worker

```bash theme={null}
tai backend worker --max-jobs 10
```

The worker and the enqueue side both connect with these settings. The worker's
connect at start follows `ARQ_RETRY_ATTEMPTS`: with the default `0`, a worker
started before Redis is reachable fails at once. A running worker rides a Redis
outage only within that same retry — arq's poll loop has no reconnect of its
own, so a longer outage ends the worker.

`--job-timeout` defaults to `ARQ_TASK_TIMEOUT`; an explicit flag wins.

Queue name, burst mode, result retention, and poll delay are worker CLI flags,
not env vars. `worker` is the only `tai backend` subcommand this backend accepts
— there is no beat or dashboard process, and anything else is refused by name.

## Worker lifecycle

Everything around the arq worker is the shared backend lifecycle every backend
gets, not this plugin's own: the launch waits for the app's boot self-resync
before the worker consumes (a worker running against a half-built tool registry
would fail its jobs permanently), the first SIGTERM or SIGINT asks arq for a
warm drain, a repeated one escalates to a cold stop, and the drain is awaited to
completion before the process tears down.

arq is deliberately built with its own signal handlers disabled. The host owns
the process's signal disposition and composes every subscriber onto one handler
per signal; arq's install would replace that outright and take the server's
teardown with it, which is what makes a recycle drain cleanly instead of
severing in-flight jobs.

## Schedule recovery

On startup a watchdog restarts enabled schedules whose pending job was lost,
never found, or completed without rescheduling. A schedule it cannot recover
(its record throws every tick) is recorded as an operator-visible error state
rather than only logged: its `backend_list_schedules` row carries `error`
(`message`, the failure detail, and `at_iso`, an ISO-8601 timestamp), and
`backend_get_schedule` carries `recovery_error` and `recovery_failed_at`. They are
null on a healthy schedule and are cleared on any later tick that finds the schedule
healthy or restarts it.

## Quirks

* `ARQ_MANIFEST_KEY`, `ARQ_TASK_TIMEOUT`, and `ARQ_TOOL_NAME_ARG` mirror the
  host's own `BACKEND_` group. Change them in lockstep or the worker and the
  server stop agreeing. `ARQ_MANIFEST_KEY` and `ARQ_TOOL_NAME_ARG` pin wiring
  built at boot, so a change to either converges through a process recycle
  rather than in place.
* arq cannot honour a relative interval: a schedule with `relative: true` is
  refused on create, update and import.
* The schedule store holds the typed cadence; a hash in an earlier format raises
  `ScheduleStoreFormatError` on list, export, get and update until the keys matching
  `ArqSettings.arq_schedule_pattern` are deleted and the schedules re-created.
* A dispatched tool runs once; arq re-runs a job cut by a cold stop, bounded by
  `--max-tries`.
* `ARQ_JOB_COMPLETION_WAIT` must cover the longest job, and the deployment's
  termination grace period must be at least as long, or a drain still severs
  running work. arq cancels running jobs on signal unless this is non-zero.

## See also

* [Backends](/concepts/backends) — the contract all three shipped backends implement.
* [Manage a fleet](/operate/manage-a-fleet) — reading the live worker census.
* [Schedule a tool](/guides/schedule-a-tool) — putting work on a schedule.


# backend-celery
Source: https://docs.tai42.ai/plugins/tai42/backend-celery

Celery execution backend for the TAI ecosystem — worker/beat/flower runtime, prefork-pool turnover on worker-bus ops, and RedBeat scheduling.

> [!NOTE]
>
> `Backend` plugin · listing `tai42/backend-celery`

## Install

```bash theme={null}
tai plugins install tai42-backend-celery
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | yes |
| Filesystem | no |

## Provides

### celery

`Backend` — Celery execution backend — worker/beat/flower runtime, prefork-pool turnover on worker-bus ops, and RedBeat scheduling.

Choose Celery when you already run RabbitMQ, or when you want beat and flower.
The broker, result backend, and RedBeat schedule store are configured
independently.

## Enable it

```yaml manifest.yml theme={null}
backend_module: tai42_backend_celery
```

A config that registers a task backend also needs the worker bus and a shared
hooks registry: `tai serve`, `tai backend`, a config reload and a config write all
refuse it unless `TAI_BUS_REDIS_URL` and `HOOKS_REDIS_URL` are set (each falls back
to `TAI_DEFAULT_REDIS_URL`). The backend process matches the events it raises
against its own hooks registry, so an in-memory one would run none of the hooks
registered through the server.

## Configuration

The `CELERY_` env group. `CELERY_BROKER_URL`, `CELERY_RESULT_BACKEND`, and
`CELERY_REDBEAT_REDIS_URL` each fall back to the shared `TAI_DEFAULT_REDIS_URL`
when unset — with the default set and `CELERY_BROKER_URL` unset, the broker
resolves to Redis (a first-class Celery broker) rather than the AMQP default. An
operator on RabbitMQ sets `CELERY_BROKER_URL` explicitly.
`CELERY_REDBEAT_REDIS_MAX_CONNECTIONS` falls back to
`TAI_DEFAULT_REDIS_MAX_CONNECTIONS` the same way. The retry and socket settings
are read from their own namespace alone.

| Variable | Default | Effect |
| - | - | - |
| `CELERY_BROKER_URL` | `amqp://localhost:5672//` | The broker. |
| `CELERY_RESULT_BACKEND` | `redis://localhost:6379/0` | Result backend. |
| `CELERY_REDBEAT_REDIS_URL` | `redis://localhost:6379/0` | Redis holding the RedBeat schedule store. |
| `CELERY_REDBEAT_KEY_PREFIX` | `redbeat:` | Key prefix for the schedule store. |
| `CELERY_REDBEAT_REDIS_MAX_CONNECTIONS` | unset | Caps the RedBeat store's connection pool; uncapped when unset. |
| `CELERY_REDBEAT_RETRY_ATTEMPTS` | `0` | Times a failed RedBeat Redis connect or command is retried, each retry logged as a warning; `0` makes one attempt. |
| `CELERY_REDBEAT_RETRY_ON_TIMEOUT` | `false` | With `CELERY_REDBEAT_RETRY_ATTEMPTS` at `0`, retries a timed-out command once at once. |
| `CELERY_REDBEAT_SOCKET_TIMEOUT` | unset | Seconds a RedBeat command may wait on its socket; redis-py's default when unset. |
| `CELERY_REDBEAT_SOCKET_CONNECT_TIMEOUT` | unset | Seconds a RedBeat connect may take; redis-py's default when unset. |
| `CELERY_RESULT_BACKEND_RETRY_ATTEMPTS` | `0` | A Redis result backend: times a failed connect or command is retried, each retry logged as a warning; `0` makes one attempt. |
| `CELERY_RESULT_BACKEND_RETRY_ON_TIMEOUT` | `false` | A Redis result backend: with `…_RETRY_ATTEMPTS` at `0`, retries a timed-out command once at once. |
| `CELERY_RESULT_BACKEND_SOCKET_TIMEOUT` | unset | A Redis result backend: seconds a command may wait on its socket; celery's default when unset. |
| `CELERY_RESULT_BACKEND_SOCKET_CONNECT_TIMEOUT` | unset | A Redis result backend: seconds a connect may take; celery's default when unset. |
| `CELERY_BROKER_RETRY_ATTEMPTS` | `0` | A Redis broker, read and write sides alike: times a failed connect or command is retried, each retry logged as a warning; `0` makes one attempt. Never retried: the reads kombu polls (a worker's task and fanout reads, a control command's reply read), where a drop raises. |
| `CELERY_BROKER_RETRY_ON_TIMEOUT` | `false` | A Redis broker: with `…_RETRY_ATTEMPTS` at `0`, retries a timed-out command once at once. |
| `CELERY_BROKER_SOCKET_TIMEOUT` | unset | A Redis broker: seconds a command may wait on its socket; kombu's default when unset. |
| `CELERY_BROKER_SOCKET_CONNECT_TIMEOUT` | unset | A Redis broker: seconds a connect may take; kombu's default when unset. |
| `CELERY_BEAT_MAX_LOOP_INTERVAL` | `60` | Maximum seconds between beat ticks. |
| `CELERY_WORKER_CONCURRENCY` | `1` | Prefork pool size. |
| `CELERY_TASK_TIMEOUT` | `300` | The dispatch job budget in seconds: the longest a task may run on the worker, and how long a synchronous dispatch waits for a result. |
| `CELERY_MANIFEST_KEY` | `MANIFEST_KEY` | Env var the live manifest JSON is written into for prefork inheritance. |
| `CELERY_TOOL_NAME_ARG` | `backend_tool_name` | Dispatch kwarg naming the target tool. |

## Redis connections

A Redis result backend takes its retry and timeouts from
`CELERY_RESULT_BACKEND_RETRY_ATTEMPTS`, `…_RETRY_ON_TIMEOUT`,
`…_SOCKET_TIMEOUT` and `…_SOCKET_CONNECT_TIMEOUT`; a Redis broker takes the
same four under `CELERY_BROKER_`, for the read and the write side alike; the
RedBeat store takes them under `CELERY_REDBEAT_`. A knob left unset keeps
celery's or kombu's own default. Every retry is logged as a warning, and the
last failure is raised.

* The plugin picks the Redis result backend and broker transport classes
  itself, so a URL from `CELERY_RESULT_BACKEND`, `CELERY_BROKER_URL`,
  `CELERY_BROKER_READ_URL` or `CELERY_BROKER_WRITE_URL` goes through them
  alike. `CELERY_LOADER` and `--loader` do not change the app's loader.
* The Redis URL forms taken are `redis://`, `rediss://` and `redis+socket://`
  (and `redis://`, `rediss://` and `unix://` for `CELERY_REDBEAT_REDIS_URL`).
  Every other Redis form — `sentinel://`, a `;` failover list, `unix://` or
  `socket://` for the result backend or the broker, `redis-cluster://` or
  `redis-sentinel://` for RedBeat — stops the app at startup with an error
  naming the setting. A non-Redis broker or result backend (AMQP, `rpc://`, …)
  is left to celery, with celery's own retries.
* With `RETRY_ATTEMPTS` unset, a Redis connection makes one attempt: a result
  write fails on the first error, a worker whose Redis read side is not
  reachable at start exits, and a publish over a Redis write side fails at
  once. Celery's own startup connect retry is switched off when the read side
  is Redis, and its publish retry when the write side is Redis, each side on
  its own; the namespace's `RETRY_ATTEMPTS` takes their place.
* A running worker that loses its Redis broker keeps reconnecting through
  celery's own loop (`broker_connection_max_retries`), logged at ERROR.
* `CELERY_BROKER_RETRY_ATTEMPTS` never retries a read kombu polls: a worker's
  task and fanout reads, and a control command's reply read (`inspect()`,
  `control`) in any process. A drop there raises at once. A worker's drop
  restarts celery's consumer, which reconnects; a control call fails with the
  connection error, and a retry of that call reconnects.
* A result wait whose Redis result backend drops is reconnected and
  re-subscribed by `CELERY_RESULT_BACKEND_RETRY_ATTEMPTS`; after each reconnect
  it reads the stored state of every task it still awaits, so a result written
  meanwhile still arrives. When that retry runs out, the wait raises the
  connection error, and the next wait, on any task, connects again, re-subscribes
  every task still awaited and reads their stored state.
* kombu's own connect step retries once after 2 s, and its channel open
  retries within `broker_connection_timeout`; neither is logged.
* flower's events, inspector and results go through the plugin's app and the
  settings above. Its broker and queue-length views open their own Redis
  connection per request, outside these settings, with no retry.

## Run the processes

```bash theme={null}
tai backend worker
tai backend beat
tai backend flower
```

## Worker lifecycle

Everything around the Celery worker is the shared backend lifecycle every backend
gets, not this plugin's own: the launch waits for the app's boot self-resync
before the worker consumes (a worker running against a half-built tool registry
would fail its jobs permanently), the worker's blocking run loop runs on a
dedicated thread so the process's event loop stays free for worker-bus ops, the
first SIGTERM or SIGINT asks Celery for a warm drain, a repeated one escalates to
a cold stop, and the drain is awaited to completion before the process tears
down.

Celery is the one shipped backend whose workers PERSIST ACROSS JOBS, so it is the
one that declares pool turnover: after a fleet op that declares an effect (the tool
registry or the compiled-template cache changed) applies, the
live manifest is re-exported into the env and the prefork pool is replaced and
confirmed before the op reports `applied`: every idle pre-restart child is gone and
the pool is back to size, while a child busy with a job finishes it, exits after it
and takes no new one, so it is not waited for. The turnover's budget is what is left of
the bus apply window (`TAI_BUS_APPLY_TIMEOUT`), measured from this worker's receipt
of the op, less a margin, so a pool that will not come back reports a truthful
`failed` rather than a guessed timeout.

`beat` and `flower` pull no queued work, so they run on the event loop and keep
whatever signal handling their own CLI installs. Nothing else runs in those
processes, so that is deliberate.

## Quirks

* `CELERY_MANIFEST_KEY` and `CELERY_TOOL_NAME_ARG` pin wiring built at boot — a
  forked child reads the env key it was given and a queued job carries the kwarg
  name its producer used — so a change to either converges through a process
  recycle rather than in place. A profile change touching one is refused on an
  unsupervised (`bare`) deployment shape, which has no way to recycle.
* On macOS, prefer the `solo` or `threads` pool — forking around the system
  resolver deadlocks.
* `backend_list_failed_tasks` is not implemented: Celery keeps no queryable
  failed-task index.
* A dispatched tool runs once: the backend never retries a tool body. A tool that
  wants retries declares a `ToolRetryPolicy`. `CELERY_TASK_TIMEOUT` is bound into
  Celery's `task_time_limit` when the worker starts, so a change converges through
  a process recycle.
* Schedules use the contract's typed cadence; this backend honours an interval's
  `relative` flag and stores schedules in RedBeat's own format.

## See also

* [Backends](/concepts/backends) — the contract all three shipped backends implement.
* [Schedule a tool](/guides/schedule-a-tool) — putting work on a schedule.


# backend-rq
Source: https://docs.tai42.ai/plugins/tai42/backend-rq

RQ execution backend for the TAI ecosystem — background tool runs and schedules over Redis.

> [!NOTE]
>
> `Backend` plugin · listing `tai42/backend-rq`

## Install

```bash theme={null}
tai plugins install tai42-backend-rq
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | yes |
| Filesystem | no |

## Provides

### rq

`Backend` — RQ execution backend — background tool runs and schedules over Redis.

RQ is Redis-only like arq, with a worker, a scheduler, and the RQ dashboard.

## Enable it

```yaml manifest.yml theme={null}
backend_module: tai42_backend_rq
```

A config that registers a task backend also needs the worker bus and a shared
hooks registry: `tai serve`, `tai backend`, a config reload and a config write all
refuse it unless `TAI_BUS_REDIS_URL` and `HOOKS_REDIS_URL` are set (each falls back
to `TAI_DEFAULT_REDIS_URL`). The backend process matches the events it raises
against its own hooks registry, so an in-memory one would run none of the hooks
registered through the server.

## Configuration

The `RQ_` env group. `RQ_REDIS_URL` and `RQ_REDIS_MAX_CONNECTIONS` fall back to
the shared `TAI_DEFAULT_REDIS_URL` / `TAI_DEFAULT_REDIS_MAX_CONNECTIONS` when
unset; a set `RQ_` value always wins. The retry and socket settings are read
from `RQ_` alone. Every Redis connection of the backend — the tools, the enqueue
path, the worker and the beat — is built from them.

| Variable | Default | Effect |
| - | - | - |
| `RQ_REDIS_URL` | `redis://localhost:6379/0` | Broker and results. |
| `RQ_REDIS_MAX_CONNECTIONS` | unset | Caps the connection pool; uncapped when unset. |
| `RQ_RETRY_ATTEMPTS` | `0` | Times a failed Redis connect or command is retried, each retry logged as a warning; `0` makes one attempt. |
| `RQ_RETRY_ON_TIMEOUT` | `false` | With `RQ_RETRY_ATTEMPTS` at `0`, retries a timed-out command once at once. |
| `RQ_SOCKET_TIMEOUT` | unset | Seconds a Redis command may wait on its socket; redis-py's default when unset. |
| `RQ_SOCKET_CONNECT_TIMEOUT` | unset | Seconds a Redis connect may take; redis-py's default when unset. |
| `RQ_RQ_PREFIX` | `rq:` | Key prefix for every RQ structure in Redis. |
| `RQ_TASK_TIMEOUT` | `300` | The dispatch job budget in seconds: the timeout the worker runs every job under, and how long a synchronous dispatch waits for a result. |
| `RQ_MANIFEST_KEY` | `MANIFEST_KEY` | Env var the worker stores the manifest JSON under, inherited by forked work-horses. |
| `RQ_TOOL_NAME_ARG` | `backend_tool_name` | Queued-job kwarg naming the target tool. |

## Run the processes

```bash theme={null}
tai backend worker --pool prefork
tai backend beat
tai backend dashboard
```

The `worker` runtime runs RQ's work loop on a dedicated thread, so the process's
event loop stays free for worker-bus ops. Its lifecycle is the shared one every
backend gets: it waits for the app to finish booting before it consumes, then
SIGTERM (or SIGINT) drains it warm — no new jobs, the current one finishes, the
process exits after teardown — and a second signal kills the running work-horse.
An idle worker stops within one dequeue poll (5s).

`beat` and `dashboard` pull no queued work, so they run on the event loop and
keep whatever signal handling their own CLI installs. Nothing else runs in those
processes, so that is deliberate.

A waiting worker that loses Redis keeps reconnecting through RQ's own loop,
logged at ERROR, outside `RQ_RETRY_ATTEMPTS`.

`beat` takes rq-scheduler's own options that are not about the connection
(`-b/--burst`, `-i/--interval`, `-v/--verbose`, `--quiet`, `--path`, `--pid`,
`-j/--job-class`) and `-u/--url`. Its connection comes from the `RQ_` settings,
like the worker's: the URL falls back to `TAI_DEFAULT_REDIS_URL`, and `-u/--url`
replaces only the URL. The scheduler loop has no reconnect of its own, so the
beat rides a Redis outage only within `RQ_RETRY_ATTEMPTS`; a longer one ends it.

The dashboard opens its own Redis connection from its `--redis-url` option,
outside the backend's connection settings, so the `RQ_` retry and timeouts do
not apply to it.

## Quirks

* RQ has no disabled-schedule state, so `backend_list_schedules` always reports a
  schedule as enabled, and disabling one deletes it.
* `backend_registered_tasks` and `backend_list_failed_tasks` are not implemented.
* The rq scheduler cannot honour a relative interval: a schedule with `relative: true`
  is refused on create, update and import.
* The worker runs every job — enqueued, or fired by the scheduler — under its own
  `RQ_TASK_TIMEOUT`, whatever timeout the job was stored with, so a change converges
  through a worker recycle.

## See also

* [Backends](/concepts/backends) — the contract all three shipped backends implement.
* [Schedule a tool](/guides/schedule-a-tool) — putting work on a schedule.


# channel-slack
Source: https://docs.tai42.ai/plugins/tai42/channel-slack

Slack channel plugin for the TAI ecosystem — delivers ask questions to a Slack channel and bridges threaded replies back to the interactions callback door.

> [!NOTE]
>
> `Channel` plugin · listing `tai42/channel-slack`

## Install

```bash theme={null}
tai plugins install tai42-channel-slack
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | no |

## Provides

### slack

`Channel` — Deliver ask questions to a Slack channel and bridge the threaded reply back.

Bridge a Slack app to an agent, or deliver `ask` questions into Slack. A
message runs an agent turn and the answer posts back in the same conversation.

## Enable it

```yaml manifest.yml theme={null}
channel_modules:
  - tai42_channel_slack
```

## Configuration

The `CHANNEL_SLACK_` env group. `CHANNEL_SLACK_REDIS_URL` (and the inherited
connection-tuning fields) point the plugin-owned correlation store.

| Variable | Default | Effect |
| - | - | - |
| `CHANNEL_SLACK_BOT_TOKEN` | unset | Bot token (`xoxb-…`, scope `chat:write`); authorizes outbound posts. Secret. |
| `CHANNEL_SLACK_SIGNING_SECRET` | unset | Events API signing secret keying the `v0` HMAC the inbound door verifies over the raw body. Secret. |
| `CHANNEL_SLACK_BOT_USER_ID` | unset | **Required.** The app's own bot user id (`U…`); a bridge route's `our_identity` and the self-message filter. |
| `CHANNEL_SLACK_ALLOWED_RECIPIENTS` | empty | Whitelist of conversation ids (`C…`/`D…`) a caller-requested recipient may name; unlisted is refused (fail closed). Comma-separated or JSON list. |
| `CHANNEL_SLACK_DEFAULT_RECIPIENT` | unset | Conversation a question without a caller-requested recipient goes to; not allowlist-checked. |
| `CHANNEL_SLACK_API_BASE_URL` | `https://slack.com/api` | Slack Web API origin. Overridable so a test stub can stand in; production leaves the default. |
| `CHANNEL_SLACK_HTTP_TIMEOUT_SECONDS` | `30` | Wall-clock budget for one outbound HTTP call. |
| `CHANNEL_SLACK_REDIS_URL` | unset | Connection for the correlation store. |

`CHANNEL_SLACK_BOT_USER_ID` is **required** whenever the channel is loaded. The
inbound door bridges under the deployment's single bot identity, so the channel's
startup hook refuses to boot without it, naming the variable — the bot never loops
on its own posts and an inbound event never fails for want of an identity.

## Point the Events API at the deployment

The Request URL is not set at boot — the channel's only startup hook is the
`CHANNEL_SLACK_BOT_USER_ID` check above. Set the **Request URL** once in your Slack app's Event
Subscriptions to `{public base URL}/api/channels/slack/inbound` and subscribe to
the message events the bot should hear. Slack verifies the URL against the
signing secret.

A `me_message` (a `/me …` post) and a `thread_broadcast` (a threaded reply also sent
to the channel) carry the participant's own text and bridge like a plain message — a
threaded broadcast resolves a pending question when it lands in an allowlisted
recipient. Other subtypes — edits (`message_changed` / `message_deleted`),
joins/leaves, `bot_message`, pins and the `message_replied` container — carry no
participant utterance and are acknowledged without bridging.

## Inbound media

A message that shares files (`subtype` `file_share`) bridges one turn per file, so
a message with several files never drops any of them. Each file's bytes are fetched
from Slack (the bot token authorizes the download and rides the request only) and
ingested into the platform's served media: the turn carries a typed attachment whose
`url` is the served `/api/interactions/media/<id>` reference, alongside the parity
`media_*` entry-params (`media_kind`, `media_id` — the served id, `media_mime_type`,
`media_sha256`, `media_filename` for a document, `media_size`). The mime major type
resolves the kind (`image`/`video`/`audio`, `application`/`text` → `document`, any
other or missing type → `file`). The message text rides the first bridged file's turn;
every other turn gets a `[kind]` placeholder, so a caption-less share is never
dropped as empty.

Entry params are bounded at the door (at most 16 keys, each value at most 512 characters,
the whole set at most 2048 bytes). Because Slack redelivers a failed webhook, this door
**drops** rather than refuses: an over-cap value is dropped on its own, an over-bound set is
dropped whole, and the participant's message still bridges. Every drop is logged at
`WARNING` (naming the door and the bound, never a value) and counted on
`tai_entry_params_dropped_total{door="slack"}`.

A fetch that fails temporarily (a Slack 5xx, a timeout, a torn download) makes the
door answer non-2xx so Slack redelivers and the turn is ingested on the retry. A
permanent failure — a missing or unreachable body, a file over the operator's byte
cap, a disallowed type, or no media store configured — bridges no turn: the
participant gets a single notice (`unsupported type`, `too large`, or `could not
receive`) and a platform event records it, while the message's other files still
bridge.

## Create a bridge route

The route's `our_identity` is the bot user id; `client_address` is the Slack
conversation id:

```bash theme={null}
tai conversations create slack-chat \
  --door channel --target-name chat --execution-key chat-bot \
  --channel slack --identity U0XXXXXXX
```

## Message ids and addresses

The conversation bridge records every message this channel sends to a participant. These are
the ids and addresses it records:

* An inbound message passes its `ts` as the medium message id. A message with several files is
  bridged as one record per file, and every record carries the same `ts`.
* `resolve_address` returns `CHANNEL_SLACK_BOT_USER_ID` and the recipient as the caller names
  it. For a user id that is not the direct-message conversation the message lands in: a
  completed send reports the `channel` from the `chat.postMessage` response, the conversation
  id the events door passes for that participant, and the message `ts`.

## Replies

A reply in a thread carries `thread_ts`, the `ts` of the thread's parent message; a message
whose `thread_ts` is its own `ts` starts the thread and quotes nothing. The channel hands the
parent's `ts` to the platform beside the reply, on every file turn of a threaded file share
too, and the platform resolves it against the conversation's own records into a typed
`reply_to` (`{message_id, status, text}`): a `tool` target reads it in its payload, an `agent`
target through `start_expr`. An option-button tap is a reply to the message holding the
buttons. A form modal submission names no message, so it quotes none.

When the reply answers a pending question, the asker receives the same `reply_to` beside the
unchanged answer, and a tap's `reply_id` entry parameter as its `params`. A thread reply or a
tap that finds no pending question bridges into the conversation with the same quoted id.

## Working-on-it signal

Slack shows no bot typing indicator: the Web API exposes none for a bot user (only
the RTM/Socket `user_typing` frame this plugin does not use), so this channel emits
no working-on-it signal while a turn runs. The answer posts back when it is ready.

## Form questions

An `ask` with `answer_format: form` posts a **Fill form** button that opens a Block
Kit modal. Schema properties map to controls — a short `enum` to a radio group and a
longer one to a select, an array of strings to a checkbox group or multi-select, a
date to a date picker, a boolean to a two-option radio (Yes/No, or the caller's words), a
number to a number input — and the
per-send layout drives display blocks, a review step, conditional fields and mid-form
reactions. A string field may name an `inputMode` for the kind of text it collects:
`email` draws an email text input and `url` a url text input; a `format: email` field
draws the email text input too. A property may also name a `control`: `chips` on a
choice, `textarea` on a `string`.

**A field's declared shape** is checked inside the modal: a number's inclusive
`minimum`/`maximum` is drawn as the number input's `min_value`/`max_value` (an
integer's rounded inward to whole numbers; bounds no value can meet are refused when
the form is asked, on every channel), a text length bound as the text input's own (below), and every
other shape (`pattern`, the email shape, an exclusive bound, a date bound or range,
a selection count) by the answer door on submit — the modal never closes on a refusal: the door's plain
sentence for the failing field (*Enter a valid email address*) is pinned under that
field (wrapped by the caller's `wording.answer.rejected` when set), and the person
corrects it in place.

A field may carry a **second line** of text (its schema `description`), drawn as the
input block's hint under the control; a per-send option may carry one too (its
`description`), drawn as the option's description under its label. Each is capped at
Slack's own limit (an option description at 75 characters) and an over-cap value is
refused loudly at delivery, never truncated.

Slack-specific behaviour (the documented degrades):

* **Dates** carry no drawable bounds — Slack's date picker has no min/max/disabled
  dates and no range control — so a date bound, an unavailable-days rule or a range
  (two date fields) is **enforced on submit** and shown as an inline error on the
  field, not prevented in the picker.
* **Range times.** A time paired with a range end (a `format: time` field whose `timeOf`
  names that end) draws as Slack's time picker (`HH:mm`, 24-hour, no seconds) right after
  its date picker, wherever the schema declares it, and a review page reads it back right
  after its date. An end time before the start time on the same day is enforced on submit
  and pinned under the end time's picker.
* **Input kinds.** Slack has no numeric or phone keyboard hint on a text element, so a
  string field whose `inputMode` is `numeric`, `decimal` or `tel` renders as a plain
  text input; only `email` and `url` draw a distinct Slack text element. `inputMode`
  selects the control, it never validates — the value is always the string typed.
* **Chips.** Slack has no chip input, so `control: chips` draws the shape's default
  choice control (a radio group/select for a single string, a checkbox
  group/multi-select for an array of strings).
* **Text length bounds.** A declared `maxLength`/`minLength` on a `string` is drawn as
  Slack's `max_length`/`min_length` on both the single-line plain text input and the
  multi-line textarea (`control: textarea`), so Slack shows and enforces the maximum. A
  `maxLength` above Slack's 3000 limit is refused loudly at delivery, never truncated.
  Slack's `email`/`url` text elements accept no length bound, so a declared bound is not
  drawn on them — it stays enforced at the answer door.
* **Buttons and title.** The open button reads `wording.form.open` (else *Fill form*,
  cap 75); the modal's submit reads the **last** page's `button_label` (else — for a
  form with no pages — the caller's `wording.form.submit`, else *Submit*) — a
  non-terminal page's label is not drawn; the close reads `wording.form.cancel`
  (else *Cancel*) and the title reads `wording.form.title` (else *Please respond*), each
  capped at 24 characters and read off the record on open and every re-render.
  `wording.form.back` draws nothing (one surface). A `wording.choice.label` and a non-form
  ask's `wording.answer` controls draw nothing on Slack (inline choices, a text-link
  Tier-1 ask).
* **Field placeholders.** A field's `wording.form.fields[name].choice_label` draws as the
  `placeholder` of that field's **select** (`static_select`/`multi_static_select`), capped
  at Slack's 150-character placeholder limit and refused loudly over it; a radio or checkbox
  group has no placeholder slot, so it draws none. Absent, the select shows Slack's own
  default prompt.
* **Yes/no words.** A boolean field's two radio options read
  `wording.form.fields[name].true_label` and `false_label` (else *Yes* / *No*), each capped
  at Slack's 75-character option-text limit and refused loudly at send over it; the review
  readback shows the same words.
* **Review line.** The review step's empty readback (before anything is filled) reads
  `wording.form.review_empty` (else *No answers to review yet.*), capped at Slack's
  3000-character section-text limit.
* **Message lines.** A Tier-1 ask's link line and deadline line read `wording.lines.answer_link`
  (`{url}` filled with the callback URL) and `wording.lines.deadline` (`{deadline}` filled with
  the ISO instant); a Tier-2 ask composes `wording.lines.reply` and the deadline line, and lists
  its choices through `wording.lines.options` (`{options}` filled with the joined list). Each is
  a plain substitution; absent, the platform's own line is used.
* **Refusal sentence.** When the door rejects a modal submission in place, the modal's inline
  error reads `wording.answer.rejected` (its optional `{reason}` token filled with the door's
  reason, and left empty when the door gave none), else the door's reason, else a generic
  correction line. The thread-reply rejection notice draws the same caller sentence through
  the shared answer ladder.
* **Form no longer available.** When the form's question is gone — its record expired before
  the submit, or the door reports the ask gone — the modal's error reads
  `wording.status.unavailable`, else *This question is no longer available; it has expired.*
  The line rides the modal's own `private_metadata`, so it reaches the person even after the
  record is gone; a line that pushes `private_metadata` past Slack's 3000-character limit is
  refused at send.
* **Display and review.** A page's heading/body/image blocks render as
  `header`/`section`/`image`; a review page is a final titled readback group in the
  single modal (Slack has no native multi-step, so no pushed confirmation view).
* **Conditional fields** show/hide by the platform re-rendering the modal
  (`views.update`) on the controlling field's change — platform logic, never a call
  to the form's consumer; the predicate is also enforced on submit.
* **Reacting forms** route a reacting field's change (and the submit check) through
  the platform's reaction seam and apply the result with `views.update`. A
  page-advance trigger has no event on Slack's single-surface modal. When a reaction
  fails, or returns an update the modal cannot draw, the person reads
  `wording.form.update_failed` (as a banner on the re-rendered modal, or as the submit's
  inline error), else *Sorry, this form could not be updated right now. Please try again.*
  Its optional `{reason}` token takes the reason a reaction raised as `FormReactionError`,
  and is left empty for any other failure. A reaction reason is at most 500 characters, so
  the line with each token filled at that bound must fit Slack's 3000-character section-text
  limit; a longer line is refused at send.
* **Field errors.** The modal shows errors per field and draws no `wording.form.error_line`;
  a missing required value is the Slack client's own check.

## See also

* [Client conversations](/concepts/client-conversations) — the bridge model and delivery outcomes.
* [Conversation bridge](/reference/conversation-bridge) — every setting and the authorization model.


# channel-telegram
Source: https://docs.tai42.ai/plugins/tai42/channel-telegram

Telegram channel plugin for the TAI ecosystem — delivers ask questions to a Telegram chat and bridges the typed reply back to the interactions callback door.

> [!NOTE]
>
> `Channel` plugin · listing `tai42/channel-telegram`

## Install

```bash theme={null}
tai plugins install tai42-channel-telegram
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | no |

## Provides

### telegram

`Channel` — Deliver ask questions to a Telegram chat and bridge the typed reply back.

Bridge a Telegram bot to an agent, or deliver `ask` questions into a chat. A
message runs an agent turn and the answer comes back in the same chat.

## Enable it

```yaml manifest.yml theme={null}
channel_modules:
  - tai42_channel_telegram
```

## Configuration

The `CHANNEL_TELEGRAM_` env group. `CHANNEL_TELEGRAM_REDIS_URL` (and the
inherited connection-tuning fields) point the plugin-owned correlation store.

| Variable | Default | Effect |
| - | - | - |
| `CHANNEL_TELEGRAM_BOT_TOKEN` | unset | Bot credential from BotFather; the auth for outbound sends. Secret. |
| `CHANNEL_TELEGRAM_WEBHOOK_SECRET` | unset | Echoed by Telegram in `X-Telegram-Bot-Api-Secret-Token`; the inbound door compares it constant-time and fails closed when unset. Secret. |
| `CHANNEL_TELEGRAM_PUBLIC_BASE_URL` | unset | This deployment's public origin; the startup hook builds the webhook URL from it. |
| `CHANNEL_TELEGRAM_ALLOWED_RECIPIENTS` | empty | Whitelist of chats (numeric chat id or `@username`) a caller-supplied recipient may name. Comma-separated or JSON list. |
| `CHANNEL_TELEGRAM_DEFAULT_RECIPIENT` | unset | Chat delivered to when the caller names none; not allowlist-checked. |
| `CHANNEL_TELEGRAM_HTTP_TIMEOUT_SECONDS` | `30` | Wall-clock budget for one outbound HTTP call. |
| `CHANNEL_TELEGRAM_OPTION_TAP_TTL_SECONDS` | `86400` | How long a notification's tappable options stay resolvable, so a later tap still bridges the option's text. A select `ask` uses its own remaining answer time instead. |
| `CHANNEL_TELEGRAM_API_BASE_URL` | `https://api.telegram.org` | Bot API origin. Overridable so a test stub can stand in; production leaves the default. |
| `CHANNEL_TELEGRAM_REDIS_URL` | unset | Connection for the correlation store. |

`CHANNEL_TELEGRAM_BOT_TOKEN`, `CHANNEL_TELEGRAM_WEBHOOK_SECRET` and
`CHANNEL_TELEGRAM_PUBLIC_BASE_URL` are **required**, and so is at least one of
`CHANNEL_TELEGRAM_DEFAULT_RECIPIENT` and `CHANNEL_TELEGRAM_ALLOWED_RECIPIENTS`: the
startup hook refuses to boot without them, naming the missing variable.

## Webhook registration is automatic

Unlike the other channels, Telegram's webhook is registered **automatically**: on
startup the plugin calls `setWebhook` (idempotent) to point Telegram at
`{PUBLIC_BASE_URL}/api/channels/telegram/inbound` with the secret token. You do
not configure it by hand. A failed `setWebhook` call, including an unreachable Bot
API, aborts startup.

## Create a bridge route

A Telegram route's `our_identity` is the bot's **numeric id** — the digits before
the `:` in the bot token. `client_address` is the numeric chat id, so each chat
holds its own conversation:

```bash theme={null}
tai conversations create tg-chat \
  --door channel --target-name chat --execution-key chat-bot \
  --channel telegram --identity 123456
```

## Rich messages

A notification's rich shapes map onto native Bot API sends: tappable **options**
render as an inline keyboard (reply options as callback buttons, link options as url
buttons), **sections** degrade to grouped buttons with each title as a text header
(Telegram has no native sectioned list), a media **header** rides the body as its
caption when it fits (else a separate message), a **footer** is a trailing italic
line, file **media** sends by kind (`sendPhoto`/`sendDocument`/`sendVideo`/`sendAudio`),
and a **location** is `sendLocation` (or `sendVenue` with a name and address). Telegram
has no vendor **templates** and no ask-less **form** notifications, so the channel
declines those capabilities rather than silently dropping them.

A bridged tap on an option with an **author-set id** carries that id back as
`params.reply_id` (and a sectioned row's description as `params.reply_description`) —
opaque enrichment a `tool` target can read from the turn's `params`.

Entry params are bounded at the door (at most 16 keys, each value at most 512 characters,
the whole set at most 2048 bytes). Because Telegram redelivers a failed webhook, this door
**drops** rather than refuses: an over-cap value is dropped on its own, an over-bound set is
dropped whole, and the participant's message still bridges. Every drop is logged at
`WARNING` (naming the door and the bound, never a value) and counted on
`tai_entry_params_dropped_total{door="telegram"}`.

## Inbound media

A message carrying media is fetched from Telegram and ingested into the platform's
served media. A **photo** (largest size), **document**, **audio**, **voice**,
**video**, **video\_note**, **animation**, or **sticker** has its bytes pulled — via
`getFile` and the file host — through the ingestion seam, which caps, sniffs, stores,
and mints a served reference. The message then bridges as one turn whose text is the
caption when present, else a non-blank placeholder (`[voice message]`,
`[document: <name>]`, or the bracketed kind), carrying BOTH a typed **attachment** (the
served `MediaItem` a tool consumer reads as structured content) and the parity `media_*`
entry-params: `media_kind` (`image`/`document`/`audio`/`video`/`sticker`), `media_id`
(the **served** media reference, not the raw Telegram `file_id`), `media_mime_type` (the
sniffed-and-agreed type), `media_size` (the actual bytes stored), and, where they apply,
`media_filename` (the sanitised display name), `media_voice` (a voice note), and
`sticker_animated`. The placeholder label and `media_filename` both use the sanitised
name, never the raw vendor filename.

A media message that **replies** to a pending question answers it just as a text reply
does: the ask is resolved with the caption (or the placeholder) as the answer text and the
`media_*` parameters, while the typed attachment rides only a fresh-turn bridge (the answer
carries text and parameters). A media reply that cannot be received leaves the ask pending.

If the media cannot be received, the participant gets one generic notice and a platform
event records why — `too_large` (over the operator's per-kind cap), `unsupported_type`
(a disallowed or mismatched type), or `could_not_receive` (a gone/expired file, a store
outage, or an unfetchable source). A caption on a rejected media is still bridged as a
text-only turn, so the participant's words are never lost. A transient failure (a
timeout, a 5xx, or a torn read) is not acked, so Telegram redelivers the update — the
update id dedupes a redelivery that later succeeds.

Content Telegram can send that this channel does not map to a media kind — a **poll**,
**dice**, **venue**, **contact**, **location**, or **game** — is not bridged: the
participant gets one generic "unsupported" notice and a platform event records the drop,
so nothing is silently lost.

## Message ids and addresses

The conversation bridge records every message this channel sends to a participant. These are
the ids and addresses it records:

* An inbound message passes its `message_id` as the medium message id.
* `resolve_address` returns the bot's numeric id and the target as the caller names it, which
  may be an `@username`. Telegram resolves the target only when it sends: a completed send
  reports the numeric `chat.id` from the Bot API response, the id an inbound message from that
  chat carries, and the `message_id` of each message sent. A send to an `@username` is
  therefore recorded in the thread of its numeric chat.

## Replies

A message sent as a reply carries `reply_to_message.message_id`, the id of the message it
quotes in the same chat. The channel hands that id to the platform beside the message, and
the platform resolves it against the conversation's own records into a typed `reply_to`
(`{message_id, status, text}`): a `tool` target reads it in its payload, an `agent` target
through `start_expr`. An inline-keyboard tap is a reply to the message holding the keyboard.
A message posted in a forum topic, whose `reply_to_message` Telegram fills with the topic's
first message, is a reply only when the participant replied to another message. A reply to a
message of another chat (`external_reply`) names no message of this chat, so it quotes none.

When the reply answers a pending question, the asker receives the same `reply_to` beside the
unchanged answer, and the reply's entry parameters (a tap's `reply_id` / `reply_description`,
a media reply's `media_*`) as its `params`.

## Working-on-it signal

While a message runs its turn, the platform keeps Telegram's **typing action**
alive: it re-issues `sendChatAction "typing"` ahead of the action's \~5 s lifetime
until the reply is sent, so the chat shows the bot typing for the whole wait rather
than for a single burst at receipt. The refresh is bounded by the
`CONVERSATIONS_WORKING_SIGNAL_MAX_SECONDS` ceiling (`0` disables it entirely), with
`CONVERSATIONS_WORKING_SIGNAL_REFRESH_MARGIN_SECONDS` the margin it refreshes ahead
of each lapse.

## The bot token stays out of logs

The Bot API carries the token in every request path (`/bot<id>:<secret>/…`), and
`httpx` logs each request line at INFO. Loading the channel registers a token mask
with the kit's transport-log redaction (`tai42_kit.logging.register_transport_redaction`),
so every `httpx`/`httpcore` record shows `/bot<redacted>/…` before any handler
formats it.

## See also

* [Client conversations](/concepts/client-conversations) — the bridge model and delivery outcomes.
* [Conversation bridge](/reference/conversation-bridge) — every setting and the authorization model.


# channel-twilio
Source: https://docs.tai42.ai/plugins/tai42/channel-twilio

Twilio SMS/WhatsApp channel plugin for the TAI ecosystem — delivers ask questions to a human's phone and bridges the reply back.

> [!NOTE]
>
> `Channel` plugin · listing `tai42/channel-twilio`

## Install

```bash theme={null}
tai plugins install tai42-channel-twilio
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | no |

## Provides

### twilio

`Channel` — Deliver ask questions to a phone over Twilio SMS/WhatsApp and bridge the reply back.

Bridge a WhatsApp number carried by Twilio to an agent.

## Enable it

```yaml manifest.yml theme={null}
channel_modules:
  - tai42_channel_twilio
```

## Configuration

The `CHANNEL_TWILIO_` env group. `CHANNEL_TWILIO_REDIS_URL` (and the inherited
connection-tuning fields) point the plugin-owned correlation store.

| Variable | Default | Effect |
| - | - | - |
| `CHANNEL_TWILIO_ACCOUNT_SID` | unset | Twilio account SID. |
| `CHANNEL_TWILIO_AUTH_TOKEN` | unset | Authenticates the outbound send and keys the inbound signature check (a mis-signed webhook is rejected). Secret. |
| `CHANNEL_TWILIO_FROM` | unset | The WhatsApp sender, `whatsapp:`-prefixed (Twilio's `From`). |
| `CHANNEL_TWILIO_ALLOWED_RECIPIENTS` | empty | Whitelist of `To` numbers a caller-requested recipient must be on. Comma-separated or JSON list. |
| `CHANNEL_TWILIO_DEFAULT_RECIPIENT` | unset | `To` number used when the caller requests none; not allowlist-checked. |
| `CHANNEL_TWILIO_API_BASE_URL` | `https://api.twilio.com/2010-04-01` | Twilio REST API origin (carries the API version prefix). Overridable so a test stub can stand in; production leaves the default. |
| `CHANNEL_TWILIO_HTTP_TIMEOUT_SECONDS` | `30` | Timeout for the outbound send and the loopback answer forward. |
| `CHANNEL_TWILIO_DEDUPE_TTL` | `172800` | Seconds a handled `MessageSid` stays remembered (replay guard). |
| `CHANNEL_TWILIO_REDIS_URL` | unset | Connection for the correlation store. |

## Point the webhooks at the deployment

Twilio calls two webhooks (configured in the Twilio console or REST — the plugin
never mutates your Twilio account):

* **Inbound message** (HTTP POST) → `{public base URL}/api/channels/twilio/inbound`
* **Delivery status callback** (HTTP POST) → `{public base URL}/api/channels/twilio/status`

Configure the inbound webhook URL with `#rp=5xx` (and `#rc=` of at least 1) so a message
refused while the server reloads is delivered again: Twilio retries only on the failures its
retry policy names, and a reload answers a retriable `503`.

The status callback surfaces a **late** delivery outcome. For a **bridge**
message Twilio accepts the send, then posts a `failed`/`undelivered` status,
which flips the answer record to `failed` (this is how the WhatsApp 24-hour
service window is surfaced on the async path); a `delivered` status confirms it.
For a **`notify_user` send** (which runs no bridge record) the status is
resolved to that send and posted as a `delivery_receipt` event onto its
monitoring trace — `failed` as an `ERROR`. A status neither owns is acknowledged
and ignored.

## Inbound media

A message that carries media (`NumMedia > 0`) bridges as a turn per media item.
Each item's bytes are fetched from Twilio (`MediaUrl{N}`, HTTP Basic auth,
following the vendor's redirect to its CDN) and ingested into the platform's
served media store: the turn gets a typed attachment whose url is
`/api/interactions/media/<id>`, plus the parity `media_*` entry-params
(`media_kind`, `media_id`, `media_mime_type`, `media_sha256`, `media_size`, and
`media_filename` for a document) carrying the served id. The `MediaContentType{N}`
major type resolves the kind (`image`/`audio`/`video`, `application`/`text` →
`document`, otherwise `file`). The `Body` caption rides the first item's text; an
item with no caption gets a `[kind]` placeholder (a document reads
`[document: <name>]` from the platform-sanitised filename), so a media message with
a blank body is never dropped as empty.

Entry params are bounded at the door (at most 16 keys, each value at most 512 characters,
the whole set at most 2048 bytes). Because Twilio redelivers a failed webhook, this door
**drops** rather than refuses: an over-cap value is dropped on its own, an over-bound set is
dropped whole, and the participant's message still bridges. Every drop is logged at
`WARNING` (naming the door and the bound, never a value) and counted on
`tai_entry_params_dropped_total{door="twilio"}`.

When an item cannot be received, the participant is notified once and the message
is acknowledged, never silently dropped: a gone media, an unfetchable byte source,
or no configured store reads as *could not receive*; a file over the platform cap as
*too large*; a disallowed content type as *unsupported*. A caption on a rejected
first item is still bridged as its own text turn. A transient fault (a `5xx` or
timeout from Twilio or its CDN, a torn read) instead returns a non-2xx webhook so
Twilio redelivers; the `MessageSid` dedupe keeps the redelivery from
double-processing. A message with no body and no media stays the legitimate
acknowledged drop.

## Create a bridge route

`our_identity` is the number the client texts — the Twilio WhatsApp sender,
`whatsapp:`-prefixed:

```bash theme={null}
tai conversations create chat-line \
  --door channel --target-name chat --execution-key chat-bot \
  --channel twilio --identity whatsapp:+14155238886
```

A `(channel, identity)` pair may be claimed by only one route; more senders are
more rows.

## Reply window

WhatsApp delivers a freeform reply only inside a 24-hour window opened by the
client's last message. For a `whatsapp:` pair the channel tracks that window and
reports it on every bridged turn as `turn.reply_window` (`{state, closes_at}`), so
a route's `start_expr`, `reply_expr` or flow can see it before replying:

* each new inbound message on the pair opens the window for 24 hours from the
  moment the webhook first receives it; a redelivered `MessageSid` keeps that
  first receipt, so a retry never moves the window;
* `state` is `open` (until `closes_at`, UTC, in whole seconds) or `closed`
  (never opened, or expired);
* an SMS pair has no such window and reads `none`.

The window lives in the channel's Redis (`CHANNEL_TWILIO_REDIS_URL`), one key per
pair that expires when the window closes, plus one first-receipt key per
WhatsApp `MessageSid` that expires after 24 hours; there is no setting. The state is read
once per turn, so a turn that runs past `closes_at` may still see `open`; Twilio's
63016 rejection of an out-of-window send stays the final check.

## Message ids and addresses

The conversation bridge records every message this channel sends to a participant. These are
the ids and addresses it records:

* An inbound message passes its `MessageSid` as the medium message id. A message with several
  media items is bridged as one record per item, and every record carries the same
  `MessageSid`.
* `resolve_address` returns the "From" number (the route's identity, else `CHANNEL_TWILIO_FROM`)
  and the "To" number, both as the inbound webhook passes them, a `whatsapp:` prefix included.
  A completed send reports the same pair and the message's `sid`.

## Replies

On WhatsApp, a message sent as a reply to a message from the last 7 days carries
`OriginalRepliedMessageSid`, the `MessageSid` of the message it quotes. The channel hands that
sid to the platform beside the message, on every media item of the message too, and the
platform resolves it against the conversation's own records into a typed `reply_to`
(`{message_id, status, text}`): a `tool` target reads it in its payload, an `agent` target
through `start_expr`. When the reply answers a pending question, the asker receives the same
`reply_to` beside the unchanged answer. An SMS has no reply field, so it quotes nothing, and
the channel sends no tappable buttons, so no tap arrives.

## Working-on-it signal

SMS and WhatsApp-over-Twilio carry no typing indicator, so this channel emits no
working-on-it signal while a turn runs. The answer is delivered when it is ready.

## See also

* [Client conversations](/concepts/client-conversations) — the bridge model and delivery outcomes.
* [Conversation bridge](/reference/conversation-bridge) — every setting and the authorization model.


# channel-web
Source: https://docs.tai42.ai/plugins/tai42/channel-web

Public web chat channel plugin for the TAI ecosystem — hosts a visitor chat page, delivers ask questions into it, and bridges the reply back.

> [!NOTE]
>
> `Channel` plugin · listing `tai42/channel-web`

## Install

```bash theme={null}
tai plugins install tai42-channel-web
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | no |

## Provides

### web

`Channel` — Deliver ask questions to a visitor in the public chat page and bridge the reply back.

### web

`Studio plugin` — The entry-gate and words panels on a web route's drill-in.

The web channel hosts a standalone chat page for anonymous visitors: it serves
the page, mints a session cookie, and bridges each message through the
conversation bridge — no vendor account, and no account for the visitor. Unlike
the messaging channels it is both the chat surface **and** the transport, and it
holds no vendor secret: the doors are public and authenticate the visitor by the
session cookie alone.

## Enable it

```yaml manifest.yml theme={null}
channel_modules:
  - tai42_channel_web
```

The only backing store is a plugin-owned Redis holding the session
registrations, the transcripts, and the pending-question records
(`CHANNEL_WEB_REDIS_URL`, falling back per-field to the shared `TAI_DEFAULT_*`
namespace).

## Configuration

The `CHANNEL_WEB_` env group. Defaults suit a typical deployment; the transcript,
stream, and entry-gate caps are the tunables.

| Variable | Default | Effect |
| - | - | - |
| `CHANNEL_WEB_REDIS_URL` | unset | Connection for the session, transcript, and pending-question store. |
| `CHANNEL_WEB_PAGE_TITLE` | `Chat` | The chat page's `<title>`. |
| `CHANNEL_WEB_STORE_OFF_TITLE` | `Chat is unavailable` | The heading of the page served while the deployment runs no chat store. |
| `CHANNEL_WEB_STORE_OFF_TEXT` | `This chat is not switched on. Please contact the site owner.` | The sentence of that page. |
| `CHANNEL_WEB_HTTP_TIMEOUT_SECONDS` | `30` | Timeout for the loopback answer forward to the interactions callback door. |
| `CHANNEL_WEB_SESSION_COOKIE_SECURE` | `true` | `Secure` on the session cookie. Set `false` only where the page is served over plain http (dev/e2e). |
| `CHANNEL_WEB_SESSION_TTL_SECONDS` | `2592000` | Lifetime of the session cookie and the server-side registration, refreshed on every resolving door. |
| `CHANNEL_WEB_SESSION_PENDING_TTL_SECONDS` | `600` | Lifetime a just-minted registration gets before its cookie first returns. |
| `CHANNEL_WEB_TRANSCRIPT_MAX_ENTRIES` | `1000` | `MAXLEN` cap on the browser-replay transcript stream (trimmed exactly). |
| `CHANNEL_WEB_TRANSCRIPT_TTL_SECONDS` | `2592000` | Transcript expiry, refreshed on every append. |
| `CHANNEL_WEB_BACKLOG_BATCH_ENTRIES` | `200` | Transcript entries read per page when a stream replays a backlog. |
| `CHANNEL_WEB_KEEPALIVE_SECONDS` | `15` | Seconds between SSE keepalive frames, and the live-tail block window. |
| `CHANNEL_WEB_BLOCKING_GRACE_SECONDS` | `5` | Grace added to the keepalive window bounding a black-holed Redis read. |
| `CHANNEL_WEB_MAX_STREAMS_PER_VISITOR` | `4` | Concurrent SSE streams admitted for one visitor. |
| `CHANNEL_WEB_MAX_STREAMS_TOTAL` | `500` | Concurrent SSE streams admitted across one process. |
| `CHANNEL_WEB_MAX_BODY_BYTES` | `65536` | Bounded read cap on the POST doors (over-cap is a loud 413). |
| `CHANNEL_WEB_MAX_ANSWER_RESTORES` | `5` | How often one question's record may be re-forwarded after a refused/failed forward. |
| `CHANNEL_WEB_ENTRY_ATTEMPTS_PER_WINDOW` | `10` | Entry-code guesses one client may make against a gated route per window. |
| `CHANNEL_WEB_ENTRY_THROTTLE_WINDOW_SECONDS` | `300` | Length of that throttle window. |

## Create a route and open the page

A web route binds an **identity** — an arbitrary name you choose — to the turn
that answers it.

```bash theme={null}
tai conversations create web-chat \
  --door channel --target-name chat --execution-key chat-bot \
  --channel web --identity assistant
```

The route's turn runs as the `--execution-key` you bind here; mint a
least-privilege key scoped to just what the route needs, the same way a phone
channel does in [WhatsApp to an agent](/guides/whatsapp-to-agent).

Send visitors to the chat page for that identity:

```
https://<your deployment>/api/channels/web/chat/assistant
```

## Agent-sent cards and lists

A `notify_user` addressed at a web visitor carries richer content than plain text. A
notification's `media` renders as a **media card** — this channel renders the whole media
vocabulary as real UI:

* an **image** inline (an absolute-`https` source; an `http:` or `data:` image is refused
  loudly — the page renders an image only from an https source),
* a **document** as a download card (its `filename` is the label, its caption a secondary
  line, with a download affordance),
* a **video** and an **audio** item as native `<video>`/`<audio>` players,
* a **link** as a safe outbound anchor (a new tab, `rel="noopener"`), rather than folded
  into the body text.

A notification's `options` renders a **tappable option list** (at most 10). Options are typed:
a **reply** chip sends its own text through the message door as an ordinary visitor message —
so it enters the conversation exactly as if the visitor had typed it — and, when the author set
an `id`, that id rides the send as `params.reply_id` so the flow reads which option was chosen;
a reply's optional `description` renders as a secondary line. A **link** option is a
button-styled action that opens its URL in a new tab (`rel="noopener"`) and submits nothing —
visually distinct from a reply chip. The sectioned alternative, `sections`, renders titled
groups of reply rows. An interactive card may also carry a media **header** above the body and a
muted **footer** beneath it. A notification's `location` renders as a **map-pin** element —
readable coordinates, any name/address, and an OpenStreetMap link built from the coordinates
alone (no external map tiles, so the page's CSP fetches nothing cross-origin). `options`,
`sections`, `location`, `header` and `footer` combine with `media` on one card. Templates are
**not** supported — a template is a vendor construct, refused loudly on this channel.

![A media card: an image with a caption and tappable option chips](https://mintcdn.com/tai42/yNgnruIAEOxLsZpT/plugins/images/tai42-channel-web/media-card.png?fit=max\&auto=format\&n=yNgnruIAEOxLsZpT\&q=85\&s=c7833fcf1f799b1766a483621137e4c6)

> [!WARNING]
>
> Rendering a remote card image makes the visitor's browser fetch it from the image
> host, which reveals the visitor's IP address and request timing to that host (the
> page sends no `Referer`). Point card images only at a host the visitor may reveal
> themselves to.

## Inbound attachments

A visitor can attach files to a message — an **image**, a **document**, an **audio**
clip, or a **video** — from the composer's attach button, by dragging a file onto the
conversation, or by pasting an image. Each file is uploaded on its own, ahead of the
send: the page shows a preview and a per-file progress indicator, and the visitor can
cancel an upload in flight or remove a ready file before sending. Sending the message
references the uploaded files, which then ride the turn as typed attachments — a
tool target receives them on its payload under the `attachments` key (the first
attachment also echoed on the `media_*` params), and a caption-less send is delivered
as a media-only message.

![The composer with a ready attachment in its tray, above the attach control and the message input](https://mintcdn.com/tai42/lmgVngznpyWu0zuP/plugins/images/tai42-channel-web/inbound-attachment-tray-light.png?fit=max\&auto=format\&n=lmgVngznpyWu0zuP\&q=85\&s=3da5ea841ab7e33fda33a7b427a7fa84)

The upload is a two-step exchange: the file is streamed to the upload door, which
returns a **same-origin** reference the message send binds to the turn. The visitor's
own attachments then render inline in their transcript — an image or player in the
bubble, a document as a download card — and replay for a returning visitor exactly as
any other message.

![A visitor's own message on their side of the transcript: the inbound image and a document download card](https://mintcdn.com/tai42/lmgVngznpyWu0zuP/plugins/images/tai42-channel-web/inbound-attachment-row-light.png?fit=max\&auto=format\&n=lmgVngznpyWu0zuP\&q=85\&s=4c7feaf5e0c1328cb90e55fada62ffed)

Which types are accepted and how large a file may be are the deployment's
media-ingestion settings (the `MEDIA_INGEST_` env group): each kind carries its own
byte cap and its own allowlist of accepted types. A file over the cap, of a
disallowed type, or that cannot be stored is refused with an inline message on the
file itself — never a silent drop.

## Ask-less forms

A `notify_user` carrying a `schema` renders an **ask-less form card**: the message is
the form's prompt, the schema draws the same schema-driven widget an `ask` form
question uses — but nothing waits on it. There is no deadline, no timeout, and no
pending interaction; the card simply sits in the conversation, and a submission enters
it as an ordinary participant message: the agent sees a `label: value` text (labels come from
the schema stored server-side; a tool target additionally receives the structured
values on its payload under a `form` key). `schema` requires a non-blank message (the
form needs a prompt), combines with `media` and a `location` on the same card, and excludes
`options`/`sections` and `template` — one message, one interactive surface.

The card settles like an option list, not like a question: submitting shows a local
"Sent" badge and the form **stays fillable** — a visitor may revise and submit again,
and each submission is its own message. The card is submittable for as long as it can
replay in the transcript (the submission token stored server-side ages out with the
transcript itself); after that, a submission is answered with a uniform not-found and
the card says the form is no longer available.

Submitted values are **transport, never validated**: the platform bounds their size
and nesting but does not check them against the schema — treat them exactly as you
treat typed participant text.

### Form words

A form question or an ask-less form card draws the caller's `wording` where it is set,
and the widget's own English where it is not:

* `form.update_failed` replaces the line shown when a form reaction is refused; its
  `{reason}` is the reaction door's own reason, and is empty when the door gave none.
* `form.step_progress` replaces a stepped form's "Step 1 of 2" line; it fills `{step}`
  and `{steps}`.
* For each field under `form.fields`: `required` is the line shown when a required value
  is missing, `invalid` the line for a value of the wrong shape, `true_label` and
  `false_label` the words a yes/no value reads back as on a review page, and
  `add_item`, `remove_item`, `item_label` (with `{n}`, the item's number) and `no_items`
  the words of a list field.
* `answer.rejected` replaces the line shown when an answer is refused and may be given
  again, and `answer.rejected_final` the line shown when the question can no longer be
  answered; each fills `{reason}` with the interactions door's own reason, empty when it
  gave none.

The widget draws no `form.error_line` and no `length_hint`: it shows each field's own
error next to the field.

## Unavailable messages

If a stored transcript entry cannot be rendered — a corrupt record in the replay
stream — the page shows a persistent **"This message is unavailable."** notice in its
place, ordered where the entry belonged, rather than a silent gap in the history. The
server emits a dedicated `chat.unavailable` frame for it (carrying the entry id and its
ordering timestamp) on both the backlog replay and the live tail; the corruption is
logged at `WARNING`. This is distinct from the transient error banner shown when a
frame fails to parse on the page itself.

## Answer and reaction forwarding

A web answer or a form reaction is forwarded server-side to the stored callback URL of
the pending question. Before anything is sent, that stored URL is pinned against the
callback prefix the platform mints under (`{INTERACTIONS_PUBLIC_BASE_URL}/api/interactions/callback/`):
only that exact shape — the same scheme, host and port, no userinfo, query or fragment,
one ticket segment — is accepted. A record outside it, or a deployment with no public
base, is refused: an `ERROR` log names the interaction, the reason and the host (never
the URL, which carries the ticket), the claimed question is not restored, nothing is
sent, and the door answers `500`.

When the interactions door refuses a forwarded answer (`400`), the web door answers
`400` with `code` `answer_refused` while the question may be answered again, or
`answer_retries_spent` once it has been refused as often as it may be and is gone. When
the interactions door refuses a forwarded reaction, the web door answers the same
status. Either body carries `reason`, the interactions door's own error, when that door
gave one; the widget fills it into the caller's sentence as `{reason}`.

For a question asked as sensitive, the `chat.answered` frame records that the question
was answered and carries no answer.

## Link parameters

Query parameters on the chat page URL are **captured with the visitor's session**
and delivered to the turn. A route whose target is a **tool** receives them on
its payload under a `params` key — string values, reachable from `start_expr`
as `.params.<name>`:

```
https://<your deployment>/api/channels/web/chat/assistant?topic=news&ref=abc
```

Bounds are enforced at the door — **at most 16** parameters, each key matching
`^[A-Za-z0-9_-]{1,64}$`, each value at most **512** characters, the whole set at
most **2048** bytes — and a violation is a refused page, never a silent trim: every
web door (the page, messages, forms and answers) **refuses** an over-bound set, because
each answers a waiting visitor. The
names `tai_pair` and `tai_entry` are reserved and stripped before storage. A later
navigation carrying parameters replaces the stored set; starting a new
conversation clears it. Parameter values are never logged, and `params` is
present on the payload only when the entry carried parameters.

When the visitor answers a pending question, the same parameters reach the asker as `params`
beside the answer.

> [!WARNING]
>
> A link parameter is **transport, nothing more** — no signature, no expiry, no
> interpretation. When a flow must *trust* a value, it issues its own secret token,
> delivers it in the link, and checks it in its own store. jq gating in
> `start_expr` runs before the tool does:
>
> ```bash theme={null}
> --start-expr 'if .params.key then {example_config_kwargs: {message: .message, token: .params.key}} else error("no key") end'
> ```

## Entry gate

A web route can be **gated**: the chat page is served only to a navigation
carrying a live entry code on `?tai_entry=<code>`. An ungated route is unchanged
— the gate is opt-in per identity.

Entry codes are operator-minted, multi-use, optionally expiring, revocable, and
**hashed at rest**: only a code's hash is stored, and the raw code exists only in
the mint response and the visitor's link. A missing, unknown, expired, or revoked
code — or a client that has guessed too often — is refused with **one** page,
HTTP `403`, one wording: the gate is no oracle. The gate is checked only where a
session is minted (opening the page or starting a new conversation); an existing
session is admitted without a code.

> [!WARNING]
>
> The gate admits **whoever holds a live code** — never who they are. Forwarding
> the link forwards entry. And revocation cuts **new** entries only: a visitor
> already admitted keeps a live session until its own TTL lapses. To cut off a live
> visitor you end their session, not the code they entered with.

### Operating the gate

In the Studio, a web route's drill-in carries the **Entry gate** panel: the gate
toggle, the live codes, and the mint and revoke dialogs (the plugin's studio-plugin
item `web`, shown where the deployment lists `tai42_channel_web` under
`studio_plugins`). The same lifecycle runs through four authed management doors —
call them with a platform API key.

**1. Enable the gate**

```bash theme={null}
curl -sS -X PUT "$TAI_BASE_URL/api/channels/web/gates/assistant" \
  -H "X-Api-Key: $ADMIN_KEY" -H 'Content-Type: application/json' \
  -d '{"enabled": true}'
```

**2. Mint a code and distribute the link**

The raw `code` is returned **once**; only its hash (`code_id`) is stored.

```bash theme={null}
curl -sS -X POST "$TAI_BASE_URL/api/channels/web/gates/assistant/codes" \
  -H "X-Api-Key: $ADMIN_KEY" -H 'Content-Type: application/json' \
  -d '{"label": "spring-cohort", "expires_at": "2026-12-31T00:00:00Z"}'
```

Distribute the chat URL with `?tai_entry=<code>` appended. A code is
multi-use: everyone holding the link enters.

**3. List codes**

```bash theme={null}
curl -sS "$TAI_BASE_URL/api/channels/web/gates/assistant" -H "X-Api-Key: $ADMIN_KEY"
```

Codes are listed by hash — a raw code is never re-readable.

**4. Expire or revoke**

```bash theme={null}
curl -sS -X DELETE "$TAI_BASE_URL/api/channels/web/gates/assistant/codes/<code_id>" \
  -H "X-Api-Key: $ADMIN_KEY"
```

## Words

A web route can set its own words, keyed by its identity like the entry gate. Every
member is optional; a member left unset draws the built-in English.

* `page` holds the chat page's refusal pages, each a `heading` (the page title) and a
  `text`: `not_a_navigation` (the chat URL was loaded by something other than a
  top-level navigation), `link_invalid` (the link's parameters break a bound),
  `entry_refused` (a gated route and no live entry code) and `page_unavailable` (the
  page bundle cannot be served).
* `transport` holds the sentences the widget draws when one of its requests is refused:
  `session_ended`, `wrong_site`, `not_listening`, `already_answered`, `busy`,
  `not_switched_on`, `too_long` and `not_sent` (each with `{subject}`), `failed`,
  `attachment_gone`, `attachment_already_sent`, `entry_refused`, and `answer_refused`
  and `answer_retries_spent` (each with `{reason}`, used when the question set no
  `answer.rejected` / `answer.rejected_final`). The `subject_message`,
  `subject_answer`, `subject_form` and `subject_request` members are the words
  `{subject}` is filled with. The attachment tray's upload sentences are fixed and are
  not route words.

A server's error string is never drawn as one of these sentences: it reaches the end
user only as `{reason}`. The page's other words and its `<title>` are not per-route
words; the title is `CHANNEL_WEB_PAGE_TITLE`.

In the Studio, the same drill-in carries the **Words** panel beside the entry gate: one
input per member, a save, and a clear. The same words run through three authed doors:

```bash theme={null}
# Read (404 when none are set)
curl -sS "$TAI_BASE_URL/api/channels/web/words/assistant" -H "X-Api-Key: $ADMIN_KEY"

# Replace the whole words object
curl -sS -X PUT "$TAI_BASE_URL/api/channels/web/words/assistant" \
  -H "X-Api-Key: $ADMIN_KEY" -H 'Content-Type: application/json' \
  -d '{"page": {"entry_refused": {"heading": "Private chat"}}, "transport": {"busy": "Please wait a moment."}}'

# Clear (404 when none are set)
curl -sS -X DELETE "$TAI_BASE_URL/api/channels/web/words/assistant" -H "X-Api-Key: $ADMIN_KEY"
```

A refused body answers `422` naming the first refused member
(`invalid request body: <member>: <reason>`). A body that sets nothing is refused the
same way: an empty object, an empty `page` or `transport` object, or a refusal page with
neither `heading` nor `text`. To go back to the built-in English, clear the words. The words are part of the platform backup
as the `channel_web_words` section: an import validates the whole section before it
writes anything, then replaces each listed route's words.

## Message ids and addresses

The conversation bridge records every message this channel sends to a visitor. These are the
ids and addresses it records:

* A message POST passes the id it is deduplicated by as the medium message id; the answer door
  passes the id of the `chat.answered` entry it writes.
* `resolve_address` returns the web route identity and the visitor id, from either addressing:
  the composite `"<identity>:<visitor-id>"` recipient, or the route identity beside a bare
  visitor id. A completed send reports the same pair, the one the message door passes for that
  visitor, and the id of the transcript entry it appended.
* The widget has no reply action, so a visitor message never quotes an earlier message: it
  carries no `reply_to`.

## Working-on-it signal

While a turn runs, the chat page shows its own **typing bubble** from the moment the
visitor's message is sent until the reply lands — driven entirely by the page, with
no server-driven frame. Because the page owns the indicator it never lapses
mid-turn, so this channel opts out of the platform's server-side working-on-it
refresh.

## Flood control

Every web door is public, so the app's rate limiter throttles it per caller. The plugin
declares the budgets on its routes: the chat doors (the page, its assets, the stream, the
session rotate, messages, forms, answers and reactions) charge the `channels_web` family at
120 requests a minute and 30 per 10 seconds, and the upload door charges
`channels_web_uploads` at 20 and 5. The families are declared, so they hold whatever mount
base the plugin is installed under. An operator tunes either field by field, for example
`TAI_RATE_LIMIT_FAMILIES__CHANNELS_WEB__LIMIT=240`.

The published API describes each door's real body: the page is `text/html`, an asset is
`application/octet-stream`, and the stream is `text/event-stream`.

## See also

* [Client conversations](/concepts/client-conversations) — the bridge model.
* [Conversation bridge](/reference/conversation-bridge) — the `params` payload key, route CRUD, and
  every setting.


# channel-whatsapp
Source: https://docs.tai42.ai/plugins/tai42/channel-whatsapp

Meta WhatsApp API channel plugin for the TAI ecosystem — delivers ask questions to a human on WhatsApp and bridges the reply back.

> [!NOTE]
>
> `Channel` plugin · listing `tai42/channel-whatsapp`

## Install

```bash theme={null}
tai plugins install tai42-channel-whatsapp
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | no |

## Provides

### whatsapp

`Channel` — Deliver ask questions to a human on WhatsApp via the Meta Cloud API and bridge the reply back.

Bridge a WhatsApp number carried by the Meta Cloud API to an agent, or deliver
`ask` questions into it. Unlike Twilio, this channel sends interactive
controls, media, and pre-approved templates.

## Enable it

```yaml manifest.yml theme={null}
channel_modules:
  - tai42_channel_whatsapp
```

## Configuration

The `CHANNEL_WHATSAPP_` env group. `CHANNEL_WHATSAPP_REDIS_URL` (and the
inherited connection-tuning fields) point the plugin-owned correlation store.

| Variable | Default | Effect |
| - | - | - |
| `CHANNEL_WHATSAPP_ACCESS_TOKEN` | unset | Graph API bearer token for the send (one token serves many numbers). Secret. |
| `CHANNEL_WHATSAPP_APP_SECRET` | unset | Keys the `X-Hub-Signature-256` HMAC the inbound door checks over the raw body. Secret. |
| `CHANNEL_WHATSAPP_VERIFY_TOKEN` | unset | Shared secret echoed during Meta's GET webhook verification handshake. Secret. |
| `CHANNEL_WHATSAPP_API_BASE_URL` | `https://graph.facebook.com/v23.0` | Graph API origin with a pinned version. Overridable so a test stub can stand in; production leaves the default. |
| `CHANNEL_WHATSAPP_DEFAULT_PHONE_NUMBER_ID` | unset | `phone_number_id` used as the sender for `ask` when none is routed. |
| `CHANNEL_WHATSAPP_ALLOWED_RECIPIENTS` | empty | Whitelist of `wa_id`s a caller-requested recipient must be on (`ask` only). Comma-separated or JSON list. |
| `CHANNEL_WHATSAPP_HTTP_TIMEOUT_SECONDS` | `30` | Timeout for the outbound send and the loopback answer forward. |
| `CHANNEL_WHATSAPP_DEDUPE_TTL` | `172800` | Seconds a handled `wamid` stays remembered (replay guard). |
| `CHANNEL_WHATSAPP_TEMPLATE_CONTACT_WINDOW_DAYS` | `30` | Rolling "seen within N days" window for template-send recipient policy; `0` disables known-contact tracking (allowlist-only). |
| `CHANNEL_WHATSAPP_REDIS_URL` | unset | Connection for the correlation store. |
| `CHANNEL_WHATSAPP_WABA_ID` | unset | WhatsApp Business Account id that owns Flows; required on the `form` paths. |
| `CHANNEL_WHATSAPP_FLOW_PRIVATE_KEY` | unset | Business RSA-2048 private key (PEM) the Flow data endpoint decrypts with; required only for an **endpoint-driven** form (one that reacts, carries a shape the Flow cannot check itself, or draws a field per case). Secret. |
| `CHANNEL_WHATSAPP_FLOW_PRIVATE_KEY_PASSPHRASE` | unset | Passphrase for an encrypted `CHANNEL_WHATSAPP_FLOW_PRIVATE_KEY` PEM. Secret. |
| `CHANNEL_WHATSAPP_FLOW_ENDPOINT_URI` | unset | Public URL of the Flow data endpoint, configured on an endpoint-driven Flow; required only for an endpoint-driven form. |

## Point the webhook at the deployment

Meta uses a **single** webhook endpoint for verification, inbound messages, and
delivery statuses (configured in the Meta App dashboard):

* Callback URL → `{public base URL}/api/channels/whatsapp/inbound`
* Verify token → the value of `CHANNEL_WHATSAPP_VERIFY_TOKEN`

On subscribe, Meta sends a `GET` with `hub.challenge`; the door echoes it as a
`text/plain` body only when the verify token matches. Inbound messages and delivery statuses then arrive
as signed `POST`s on the same URL. A delivery status for a **bridge** message
updates its answer record (a `failed` ends it `failed`); a status for a **flow
send** (`notify_user`, which runs no bridge record) is instead posted as a
`delivery_receipt` event onto that send's monitoring trace — `failed` as an
`ERROR`. A status neither owns is acknowledged and ignored.

## Create a bridge route

`our_identity` is the number's **`phone_number_id`** (from the Meta dashboard),
not the display number:

```bash theme={null}
tai conversations create chat-line \
  --door channel --target-name chat --execution-key chat-bot \
  --channel whatsapp --identity 109999888877776
```

## Rich messages

* **Interactive select asks** — when a `select` question is delivered, its
  options render as native WhatsApp controls: a short set becomes tappable reply
  buttons, a longer set a list message. Past WhatsApp's row cap, or when an
  option's text is too long for a button or row, the ask falls back to the
  numbered-text prompt so the person always sees every option in full. Either way
  the answer is the option text.
* **Rich notifications** — `notify_user` renders the full outbound vocabulary:
  **media** (image / document / video / audio each as its own native message; a
  link appended to the body), tappable **options** (`ReplyOption` → reply
  buttons or a list, sending an authored `id` on the wire when set; a lone
  `LinkOption` → a `cta_url` URL button), multi-section **lists** with per-row
  descriptions (`sections`), a media **header** + text **footer** on an
  interactive message, a shared **location**, an **ask-less form** (`schema`, an
  in-chat Flow), and out-of-window **templates** (`header_media` +
  `body_parameters` + quick-reply/url `buttons`). A choice surface, `schema`,
  and `template` are mutually exclusive on one send; media and location may
  combine with a choice surface. A channel that cannot render a given field never
  receives it (the send gates on the matching `supports_*` capability flag).

## Form asks

A `form` ask (an `ask` whose answer is a small JSON object) renders as an in-chat
**WhatsApp Flow**: the participant fills the fields and submits, and the completed
values return as the answer. A multi-page layout renders one screen per page, and
per-send prefill values and option lists open the form already filled in. A short
string `enum` renders a radio group (longer, a dropdown), an array of strings a
checkbox group, a `format: date` a calendar picker (bounded by its date constraints); a page's
display blocks and a review page render too, and a `visibleWhen` field is shown or
hidden client-side. A field shown for several values of its controlling field is drawn
as one control per value; such a form is endpoint-driven (below), and the data endpoint
keeps the value of the case whose condition holds under the field's own name.

A string field's `inputMode` hint picks the text field's keyboard: `numeric` and
`decimal` draw the numeric keypad (it admits a decimal separator), `tel` the phone
keypad, `email` the email keyboard, and `url` degrades to a plain text field (Meta
has no `url` input-type); `text` (or no hint) is the plain text field. The value is
always submitted as the typed string. A `format: email` field draws the email keyboard
too, and its address shape is checked inside the form (below).

**Shapes are caught inside the form.** A field's declared shape stops the person on
the screen, with the field's sentence under it, before the submit leaves the form:

| Shape (schema) | Checked by |
| - | - |
| `required` | The control itself on the current screen, on every control (a date is a calendar picker, which takes `required`); the data endpoint for a value carried from an earlier screen, where the field shows the sender's `wording.form.fields[<name>].required` |
| `pattern` | The control itself on a text or numeric keyboard (drawn as Meta's `pattern`, with the field's second line — else its sentence — as the helper text Meta then requires); the data endpoint on the email or phone keyboard and on a text area |
| `integer` | The control itself (a whole-number pattern on the numeric keypad) |
| `format: time` / `date-time` | The control itself (the platform's regex as its pattern) and the data endpoint (a real calendar value) |
| `format: email` | The data endpoint (the platform's one address shape) |
| `minLength` / `maxLength` | The control's character limits (a text area has no minimum: the data endpoint checks it) |
| `minimum` / `maximum`, `exclusiveMinimum` / `exclusiveMaximum`, `multipleOf` | The data endpoint |
| `minItems` / `maxItems` | The checkbox group's or chip grid's selection limits |
| `minDate` / `maxDate` / `unavailableDates` | The calendar picker's bounds and excluded days |
| a date range's order and `minDays` / `maxDays` | The range calendar picker when the pair draws as one control; else the data endpoint |
| a range end's time order (`timeOf`: an end time before the start time on the same day) | The data endpoint |
| any other keyword | The data endpoint |

A form carrying any shape only the data endpoint checks, or a field drawn per case, is
published **endpoint-driven** (as a reacting form is): every footer calls this plugin's Flow data
endpoint, which runs the platform's one form-shape check on the screen's values (on a
step) or on the whole answer (on submit). A broken shape keeps the person on the screen:
the failing field shows its sentence under the control (Meta's `error-message`) and the
screen shows an error line; a clean step moves on, a clean submit completes the form.
The field's sentence is the sender's `wording.form.fields[<name>].required` for a missing
value and `wording.form.fields[<name>].invalid` for any other broken shape (the sender's
words, in the end user's language) when set, else this channel's own word for the
broken shape. The error line is the sender's `wording.form.error_line` when set, else a
*Label: sentence* list carrying each field's sentence or the platform's own sentence
naming the bound (*Quantity: Enter a number of at least 1*). Each field sentence is
refused at deliver past Meta's `error-message` cap — 30 characters on a text field or
text area, 80 on a calendar or choice control — naming the field and the member. Meta
documents no cap on the error line. A shape the control checks itself shows Meta's own
message on the control. When a reaction cannot update the form, the screen shows the
sender's `wording.form.update_failed` (its `{reason}` token filled with the reaction
door's reason, empty when there is none) else this channel's own failure notice.

A `control: chips` choice draws a chip grid (single-pick for a string `enum`,
multi-pick for an array of strings) for Meta's 2–20 choices, else it degrades to the
default radio/dropdown or checkbox control. Whether a field draws chips is decided by
its schema `enum`, so a send (or a reaction update) whose per-send option list for a
chip grid has fewer than 2 or more than 20 entries is refused, naming the property and
the count. A `control: textarea` string draws a
multi-line text area, and a declared `maxLength`/`minLength` is drawn as the field's
character limit (`max-chars`/`min-chars` on a single-line field, `max-length` on the
text area). A declared date range (a `rangeStart` pairing) draws as one range
CalendarPicker when both ends sit on the same page with the same visibility, no
other field depends on either end, and the form has no review page, else as two date
fields (a review page reads each field's value back as text, which a range object
cannot render); either way the answer is the two date strings. A time paired with a
range end (a `format: time` field whose `timeOf` names that end) draws as a text field
right after its date — after the range picker, the start's time and then the end's time,
when the pair draws as one control — wherever the schema declares it. WhatsApp Flows
have no time-of-day component and no time input type, so the time is typed as `HH:MM`. A review page reads each
time back right after its date too, and a yes/no field as the sender's
`wording.form.fields[<name>].true_label` / `false_label`, else *Yes* / *No*. Those
words are part of the published Flow, so a send with other words publishes its own Flow.

A field may carry a **second line** of text (its schema `description`): it draws as
the control's helper text on a text, text-area or date field, and as a caption right
after the control on a choice control (chips included) or an opt-in, which take no
helper text — inside the same `If` when the field is conditional. A date range drawn
as one range control carries each end's second line as its own caption. Helper text
is refused past 80 characters and a caption past 409 (Meta's caps), naming the property.
A per-send option may carry a second line too (its `description`): on a dropdown, radio
group or checkbox group it is drawn under the option title (at most 300 characters,
Meta's cap — a longer one is refused naming the property); a chip has no second-line
slot, so on a chip grid it is folded onto the chip's title after an em dash
(`Gold — 2-3 days`), which Meta leaves uncapped.

The platform-drawn texts of a send ride the sender's `wording` catalogue. The chat
button that opens the Flow reads `wording.form.open` (else *Fill form*, ≤20
characters), a page-less form's screen title reads `wording.form.title` (else *Form*)
and its terminal button reads `wording.form.submit` (else *Submit*, ≤35 characters),
each page's own primary button reads its `button_label` (else *Continue*/*Submit*,
≤35 characters), and a `select` ask's or options/sections notification's list-opening
button reads `wording.choice.label` (else *Choose an option*, ≤20 characters) with its
numbered-text fallback hint reading `wording.choice.reply_hint` (else *Reply with the
text of one option.*). A non-form `confirm`/`external` ask is a text link whose line
reads `wording.lines.answer_link` (its `{url}` token filled with the callback link,
else *Answer here:&#x20;*); WhatsApp draws no `wording.answer` button. When the callback
door rejects a form answer, the re-sent Flow's body reads `wording.answer.rejected`
with its `{reason}` token filled with the line: the sender's `wording.form.error_line`
when set, else the door's reason led by the field label. The token is empty when there is
neither. Without `wording.answer.rejected` the body reads a generic lead and the line.
The template is capped at deliver so the line always fits Meta's message body, and an
`error_line` longer than 500 characters is refused at deliver too.

A form that **reacts while open** (its ask declares reaction triggers), carries a
shape only the data endpoint checks, or draws a field per case (a `visibleWhen` shown for
several values) publishes as an endpoint-driven Flow whose footers
and reacting controls call this plugin's encrypted Flow **data endpoint**
(`/api/channels/whatsapp/flow-data`, which answers the encrypted reply as a `text/plain`
body); a declared reaction runs only once the screen's shapes are clean. Such a form —
an ask or an ask-less form notification alike — needs the business key material
(`CHANNEL_WHATSAPP_FLOW_PRIVATE_KEY` + `CHANNEL_WHATSAPP_FLOW_ENDPOINT_URI`, and the
public key registered for the sending number through the admin-only
`POST /api/channels/whatsapp/flow-encryption` route, which derives it from the private
key) and is refused loudly, before anything is sent, without it. See the plugin README
for the provisioning steps.

Each schema property name may use any character, while a Flow component name must be
an identifier (`[A-Za-z_][A-Za-z0-9_]*`). The channel maps each property to a unique
identifier-safe component name for the Flow it publishes, and maps the submitted values
back to the original property names before returning the answer — so the answer keys are
always the schema's own property names, whatever characters they use.

The submitted answer the Flow sends back is keyed by each field's human-readable label
(its schema `title`, else the property name), the same label its control shows, rather
than by the identifier-safe names; the channel maps those labels back to the schema keys
when it decodes the reply. The channel sends the labels in drawing order, each paired
time right after its date.

If the platform rejects a submitted answer (a value fails the answer schema at the
door — a case no in-form check could see), the **same form is re-sent** — same steps,
same prefill, with the door's reason shown above it as *Label: sentence* (*Your last
answer could not be accepted: Email address: Enter a valid email address*) — so the
participant can correct and resubmit. This repeats
up to a fixed retry cap; past the cap the participant reads the sender's
`wording.answer.rejected_final` once (its `{reason}` filled with the same line), else
this plugin's own *the form could not be processed* line, and the ask times out. A
`rejected_final` that could pass Meta's 4096-character text cap with the line filled
in is refused at deliver.

One question is open per participant at a time: a second ask to the same participant
is refused while the first is pending. When the platform withdraws the open question
(a cancel, a route's `cancel_expr`, or an erase of its thread, route or person), the
channel releases the participant at once and sends them nothing, so the next ask goes
out straight away. The withdrawn form stays in the chat; a late reply to it arrives as
a new inbound turn.

## Inbound entry parameters

When an inbound message enters the conversation **bridge** as a fresh turn (no
pending question to answer), the channel forwards opaque **entry parameters**
alongside the turn text, delivered verbatim to a `tool` target's payload under
`params`. The platform attaches no meaning and no trust; a consumer opts into the
keys it understands:

* `reply_id` (+ `reply_description` for a list row) — an interactive tap that is
  not an answer carries its question-bound wire id.
* `button_payload` — a **template quick-reply** tap (`button` message) carries the
  developer payload behind the visible button text.
* `referral_source_url` / `referral_source_id` / `referral_source_type` /
  `referral_ctwa_clid` / `referral_headline` / `referral_body` — a click-to-WhatsApp
  or QR entry (`referral`) forwards its fields.
* `media_kind` / `media_id` / `media_mime_type` / `media_sha256` / `media_size` /
  `media_filename` / `media_voice` / `sticker_animated` — an inbound **media**
  message (image/document/audio/video/sticker) bridges with its caption as the
  turn text and its ingested identity in these params (see **Inbound media** below).
* `reaction_emoji` / `reaction_message_id` — an inbound emoji **reaction**.
* `contacts_count` / `contacts` — shared **contact** card(s).

Entry params are bounded at the door (at most 16 keys, each value at most 512 characters,
the whole set at most 2048 bytes). Because Meta redelivers a failed webhook, this door
**drops** rather than refuses: an over-cap value is dropped on its own, an over-bound set is
dropped whole, and the participant's message still bridges. Every drop is logged at
`WARNING` (naming the door and the bound, never a value) and counted on
`tai_entry_params_dropped_total{door="whatsapp"}`.

Participant **media**, **location**, **contacts**, and **reactions** all bridge as
turns. An inbound **location** additionally lands as a typed `LocationElement` on
the turn (not a param).

## Replies

A message sent as a reply to an earlier one carries Meta's `context.id`, the `wamid` of
the message it quotes. The channel hands that id to the platform beside the message (never
as an entry parameter), and the platform resolves it against the conversation's own records
into a typed `reply_to` (`{message_id, status, text}`): a `tool` target reads it in its
payload, an `agent` target through `start_expr`. An interactive tap (a reply button or a
list row), a template quick-reply and a completed Flow carry the `context.id` of the message
that held the buttons or the Flow, so each is a reply to that message.

When the reply answers a pending question, the asker receives the same `reply_to` beside
the unchanged answer. WhatsApp sends no entry parameters with an answer, so the asker's
`params` is `null`. A reaction is not a reply: `reaction_message_id` names the message the
emoji was applied to.

## Inbound media

When a participant sends **media** (image / document / audio / video / sticker), the
channel looks up the Graph media object's short-lived lookaside url, streams the bytes,
and ingests them into the platform's served-media store. The bridged turn then carries
both a typed **`attachments`** entry — a `MediaItem` whose url is the served
`/api/interactions/media/<id>` reference — and the parity `media_*` params off that one
ingest (`media_id` is the served id, `media_mime_type` the sniffed-and-agreed type,
`media_sha256`/`media_size` the ingested content's digest and byte size, `media_filename`
the sanitised document name). The caption is the turn text, or a `[kind]` placeholder when
there is none.

If the bytes cannot be received, the participant is told once and the media is not bridged:

* **too large** — the object exceeds the operator's per-kind byte cap;
* **unsupported type** — the sniffed content is not on its kind's allowlist (or the declared
  and sniffed types disagree);
* **could not receive** — the media object has expired or is gone, or no media store is
  configured.

When a caption rode with a rejected media, the caption still bridges as a text-only turn so
the message is never lost. A **transient** fetch fault (a `5xx`, a timeout, or a torn read)
is not rejected: the webhook returns non-2xx, Meta redelivers, and the per-message dedupe
guards against a double turn.

Params ride only on the bridge path — a tap or quick-reply that **answers** a
pending question surfaces none (the answer path carries no params). Meta inbound
error notices (`errors[]`) are always logged at warning and never bridged; an
**unsupported-message-type** notice (`code 131051`) — participant content the
channel cannot receive — additionally sends the participant one generic
"unsupported content" reply and records a rejection event, while every other error
code stays log-only (an operator-facing vendor signal, not participant content). An
unhandled participant **content type** the plugin has no handler for likewise gets
the generic reply + event; a vendor **non-content** notification (`system` /
`request_welcome`) stays log-only. Each reply is sent once, deduped per message.

## The 24-hour window and templates

WhatsApp delivers freeform messages only inside a **24-hour service window**
opened by the client's last message. Outside it, a freeform reply is rejected
(synchronously, or later via a `failed` delivery-status webhook), and the record
ends `failed` rather than silently vanishing. Read failures with:

```bash theme={null}
tai conversations failed
```

The channel tracks that window per pair (`phone_number_id`, `wa_id`) and reports
it on every bridged turn as `turn.reply_window` (`{state, closes_at}`), so a
route's `start_expr`, `reply_expr` or flow can choose a template before Meta
refuses a freeform reply:

* every client message (text, media, reaction, an interactive tap, a Flow reply,
  an unsupported type) moves the window to its own Meta `timestamp` plus 24 hours,
  never backwards, so a redelivered or out-of-order webhook cannot shorten it; a
  timestamp ahead of the replica's clock counts as now;
* a platform notice (`system`, `request_welcome`) does not open it;
* a message whose `timestamp` is missing or unreadable opens nothing and logs a
  warning naming the message;
* `state` is `open` (until `closes_at`, UTC) or `closed` (never opened, or
  expired).

The window lives in the channel's Redis (`CHANNEL_WHATSAPP_REDIS_URL`), one key
per pair that expires when the window closes. There is no setting: the 24 hours
are Meta's rule. The state is read once per turn, so a turn that runs past
`closes_at` may still see `open`; Meta's 131047 rejection stays the final check.

A **pre-approved template** is the one message delivered outside the window. Send
one with `notify_user`'s `template` input: a `name`, a `language`, an optional
`header_media` (image/video/document), positional `body_parameters` (body-text
fills), and per-button `buttons` (a quick-reply `payload` or a url suffix). Because
a template is billed and delivered cold, the
channel fences who may receive one: the recipient must be on
`CHANNEL_WHATSAPP_ALLOWED_RECIPIENTS`, or be a **known contact** — a number the
inbound webhook received a message from within
`CHANNEL_WHATSAPP_TEMPLATE_CONTACT_WINDOW_DAYS`. A template send to a cold,
unlisted number is refused loudly.

## Message ids and addresses

The conversation bridge records every message this channel sends to a participant. These are
the ids and addresses it records:

* An inbound message, and a reply to a question, passes its `wamid` as the medium message id.
* `resolve_address` returns the sending phone number id and the recipient as the caller names
  it. A completed send reports Meta's `contacts[0].wa_id` for the recipient, the id an inbound
  message from them carries as `from`; it can differ in form from the number the send named.
  A send that went out as several messages reports every `wamid`, in send order.

## Working-on-it signal

While a message runs its turn, the platform keeps WhatsApp's **typing indicator**
alive: it re-sends the indicator ahead of Meta's \~25 s dismissal window until the
reply is sent, so the participant sees it for the whole wait rather than only the
first few seconds. The refresh is bounded by the
`CONVERSATIONS_WORKING_SIGNAL_MAX_SECONDS` ceiling (`0` disables it entirely), with
`CONVERSATIONS_WORKING_SIGNAL_REFRESH_MARGIN_SECONDS` the margin it refreshes ahead
of each lapse. An inbound message is marked **read** the moment it is received,
independent of the indicator.

## See also

* [Client conversations](/concepts/client-conversations) — the bridge model and delivery outcomes.
* [Interactions](/concepts/interactions) — the answer contract for a delivered question.
* [Conversation bridge](/reference/conversation-bridge) — every setting and the authorization model.


# Atlassian
Source: https://docs.tai42.ai/plugins/tai42/connector-atlassian

Atlassian (Jira, Confluence, Compass) OAuth connector provider on Atlassian's hosted Rovo MCP endpoint.

> [!NOTE]
>
> `Connector` plugin · listing `tai42/connector-atlassian`

## Install

```bash theme={null}
tai plugins install tai42/connector-atlassian --env CONNECTORS_ATLASSIAN_CLIENT_ID=... --env CONNECTORS_ATLASSIAN_CLIENT_SECRET=... --secret CONNECTORS_ATLASSIAN_CLIENT_SECRET
```

## Permissions

| Capability | Declared |
| - | - |
| Network | no |
| Subprocess | no |
| Filesystem | no |

## Provides

### atlassian

`Connector` — OAuth connector for Atlassian (Jira, Confluence, Compass).

Registers the `atlassian` connector: one Atlassian OAuth 2.0 (3LO) connection per
alias, unlocking three services — Jira, Confluence, and Compass. Every service is a
remote HTTP MCP endpoint hosted by Atlassian, so nothing is launched locally. The
plugin is pure descriptor data; the runtime's connector engine runs the OAuth flow,
seals the tokens, and reaches Atlassian's hosted MCP endpoint with the connection's
own token.

## Install

```bash theme={null}
tai plugins install tai42/connector-atlassian \
  --env CONNECTORS_ATLASSIAN_CLIENT_ID=... \
  --secret CONNECTORS_ATLASSIAN_CLIENT_SECRET
```

Or add it by hand to the manifest under `connectors:` (the descriptor block the
plugin provides):

```yaml manifest.yml theme={null}
connectors:
  - id: atlassian
    kind: oauth
    origin: system
    category: dev-tools
    display_name: Atlassian
    description: Connect Jira, Confluence, and Compass.
    icon_url: https://raw.githubusercontent.com/tai42ai/tai42/main/plugins/connector-atlassian/icon.png
    oauth:
      authorize: https://auth.atlassian.com/authorize
      token: https://auth.atlassian.com/oauth/token
      revoke: null
    client_id_env: CONNECTORS_ATLASSIAN_CLIENT_ID
    client_secret_env: CONNECTORS_ATLASSIAN_CLIENT_SECRET
    sub_services:
      jira:
        id: jira
        display_name: Jira
        scopes: [offline_access, read:issue:jira, write:issue:jira]
        mcp_server: {type: http, url: https://mcp.atlassian.com/v1/mcp/authv2}
    extra_authorize_params: {audience: api.atlassian.com, prompt: consent}
```

The manifest block above is trimmed to one sub-service and a short scope set for
brevity; the plugin's `tai-plugin.yml` carries the full set.

## Create the Atlassian app

Create an **OAuth 2.0 (3LO)** app in the Atlassian developer console, enable the
products you intend to offer (Jira, Confluence, Compass), and grant the app the
granular scopes listed below.

Add this exact callback URL, where `{origin}` is your deployment's public origin (or
`CONNECTORS_OAUTH_BRIDGE_URL` when you run a shared bridge):

```
{origin}/oauth-bridge.html
```

The path is the deployment's declared OAuth callback page, `HOSTED_UI_OAUTH_CALLBACK_PATH`
(default `/oauth-bridge.html`); a deployment that declares another path registers
`{origin}` plus that path instead.

Then set the client credentials on the API process:

```bash theme={null}
CONNECTORS_ATLASSIAN_CLIENT_ID=...
CONNECTORS_ATLASSIAN_CLIENT_SECRET=...
```

The engine-wide `CONNECTORS_*` settings — the key-encryption key
(`CONNECTORS_KEK`), the state HMAC key (`CONNECTORS_STATE_HMAC_KEY`), and the
redirect-URI allowlist (or `CONNECTORS_OAUTH_BRIDGE_URL` when you run a shared
bridge) — are shared by every connector and are described in
[Connectors](/concepts/connectors). The origin you registered with Atlassian must
appear in the redirect-URI allowlist, and it must be https for anything but a local
host.

## Services and scopes

Atlassian refuses an app that mixes classic and granular scopes, so every scope below
is granular.

| Service | Scopes |
| - | - |
| `jira` | `offline_access`, `read:issue:jira`, `read:issue-meta:jira`, `read:project:jira`, `read:comment:jira`, `read:attachment:jira`, `read:issue-worklog:jira`, `read:jql:jira`, `read:board-scope:jira-software`, `read:sprint:jira-software`, `write:issue:jira`, `write:comment:jira`, `write:issue-worklog:jira`, `delete:issue:jira`, `write:sprint:jira-software` |
| `confluence` | `offline_access`, `read:page:confluence`, `read:hierarchical-content:confluence`, `read:comment:confluence`, `read:space:confluence`, `write:page:confluence`, `read:content-details:confluence` |
| `compass` | `offline_access`, `read:component:compass`, `write:component:compass` |

All three services resolve to Atlassian's hosted MCP endpoint at
`https://mcp.atlassian.com/v1/mcp/authv2`. The authorize request adds
`audience=api.atlassian.com` and `prompt=consent`. `offline_access` is what makes the
refresh token available, so a connection survives the access token's expiry.

> [!WARNING]
>
> Atlassian publishes no 3LO revocation endpoint, so disconnecting removes the stored
> token from this deployment but cannot revoke it at Atlassian. Revoke the app's access
> from the Atlassian account's connected-apps screen when that matters.

## Connect an account

Each service resolves to Atlassian's hosted MCP endpoint, authorised with the
connection's own token.

## See also

* [Connectors](/concepts/connectors) — the model, the token lifecycle, and the shared engine settings.
* [Connect an OAuth provider](/guides/connect-an-oauth-provider) — the end-to-end walkthrough.


# GitHub
Source: https://docs.tai42.ai/plugins/tai42/connector-github

GitHub OAuth connector provider for the TAI ecosystem. Pure descriptor data against GitHub's hosted MCP server; ships no package.

> [!NOTE]
>
> `Connector` plugin · listing `tai42/connector-github`

## Install

```bash theme={null}
tai plugins install tai42/connector-github --env CONNECTORS_GITHUB_CLIENT_ID=... --env CONNECTORS_GITHUB_CLIENT_SECRET=... --secret CONNECTORS_GITHUB_CLIENT_SECRET
```

## Permissions

| Capability | Declared |
| - | - |
| Network | no |
| Subprocess | no |
| Filesystem | no |

## Provides

### github

`Connector` — OAuth connector for GitHub over GitHub's hosted MCP server.

Registers the `github` connector: one OAuth connection per alias against GitHub's
hosted MCP server at `https://api.githubcopilot.com/mcp/`. The plugin is pure
descriptor data and ships no package; each sub-service selects one GitHub MCP
**toolset** through the `X-MCP-Toolsets` header. The runtime's connector engine
runs the OAuth flow, seals the tokens, and reaches the MCP server over HTTP.

## Install

Install the descriptor into the running server with the CLI:

```bash theme={null}
tai plugins install tai42/connector-github \
  --env CONNECTORS_GITHUB_CLIENT_ID=... \
  --secret CONNECTORS_GITHUB_CLIENT_SECRET
```

Or add the provider by hand as a manifest `connectors:` entry (each sub-service is
one toolset):

```yaml manifest.yml theme={null}
connectors:
  - id: github
    display_name: GitHub
    description: Connect GitHub over GitHub's hosted MCP server toolsets.
    icon_url: https://raw.githubusercontent.com/tai42ai/tai42/main/plugins/connector-github/icon.png
    kind: oauth
    origin: system
    category: dev-tools
    oauth:
      authorize: https://github.com/login/oauth/authorize
      token: https://github.com/login/oauth/access_token
      revoke: null
    client_id_env: CONNECTORS_GITHUB_CLIENT_ID
    client_secret_env: CONNECTORS_GITHUB_CLIENT_SECRET
    sub_services:
      repos:
        id: repos
        display_name: Repos
        description: Repository contents, branches, commits, and file operations.
        scopes:
          - repo
        mcp_server:
          type: http
          url: https://api.githubcopilot.com/mcp/
          extra_headers:
            X-MCP-Toolsets: "repos"
      # ...one entry per toolset; see tai-plugin.yml for the full set.
```

## Register a GitHub App

Register a **GitHub App** (not a plain OAuth App) and turn ON **"Expire user
authorization tokens"**. With expiry enabled the token response carries a
`refresh_token` and `expires_in`, which the platform requires on Connect. A plain
OAuth App issues no refresh token and will fail Connect loudly.

* authorize: `https://github.com/login/oauth/authorize`
* token: `https://github.com/login/oauth/access_token`

For a GitHub App the effective grant is the App's configured **permissions** (the
`scope` query param is ignored). Grant the permissions the toolsets you enable
need — Contents and Metadata (repos), Issues, Pull requests, Actions, Discussions,
Code scanning alerts, Secret scanning alerts, Dependabot alerts, and the
organization/member read permissions.

Add this exact callback URL, where `{origin}` is your deployment's public origin
(or `CONNECTORS_OAUTH_BRIDGE_URL` when you run a shared bridge):

```
{origin}/oauth-bridge.html
```

The path is the deployment's declared OAuth callback page, `HOSTED_UI_OAUTH_CALLBACK_PATH`
(default `/oauth-bridge.html`); a deployment that declares another path registers
`{origin}` plus that path instead.

Then set the client credentials on the API process:

```bash theme={null}
CONNECTORS_GITHUB_CLIENT_ID=...
CONNECTORS_GITHUB_CLIENT_SECRET=...
```

The engine-wide `CONNECTORS_*` settings — the key-encryption key
(`CONNECTORS_KEK`), the state HMAC key (`CONNECTORS_STATE_HMAC_KEY`), and the
redirect-URI allowlist (or `CONNECTORS_OAUTH_BRIDGE_URL`) — are shared by every
connector and are described in [Connectors](/concepts/connectors). The origin you
registered with GitHub must appear in the redirect-URI allowlist, and it must be
https for anything but a local host.

## Toolsets and scopes

Each sub-service is one GitHub MCP toolset, selected by the `X-MCP-Toolsets`
header. The scope list names the OAuth-App scope each toolset needs; for a GitHub
App map each to the equivalent App permission.

| Toolset | Scopes |
| - | - |
| `repos` | `repo` |
| `issues` | `repo` |
| `pull_requests` | `repo` |
| `actions` | `repo`, `workflow` |
| `discussions` | `repo`, `read:discussion` |
| `code_security` | `repo`, `security_events` |
| `secret_protection` | `repo`, `security_events` |
| `dependabot` | `repo` |
| `notifications` | `notifications` |
| `orgs` | `read:org` |
| `users` | `read:user` |
| `gists` | `gist` |

## See also

* [Connectors](/concepts/connectors) — the model, the token lifecycle, and the shared engine settings.
* [Connect an OAuth provider](/guides/connect-an-oauth-provider) — the end-to-end walkthrough.


# Google
Source: https://docs.tai42.ai/plugins/tai42/connector-google

Google Workspace OAuth connector provider (Gmail, Calendar, Drive, Docs, Sheets, Slides, Chat, People) on Google's hosted Workspace MCP servers.

> [!NOTE]
>
> `Connector` plugin · listing `tai42/connector-google`

## Install

```bash theme={null}
tai plugins install tai42/connector-google --env CONNECTORS_GOOGLE_CLIENT_ID=... --env CONNECTORS_GOOGLE_CLIENT_SECRET=... --secret CONNECTORS_GOOGLE_CLIENT_SECRET
```

## Permissions

| Capability | Declared |
| - | - |
| Network | no |
| Subprocess | no |
| Filesystem | no |

## Provides

### google

`Connector` — OAuth connector for Google Workspace on Google's hosted MCP servers.

Registers the `google` connector: one OAuth connection per alias, each unlocking
Google Workspace MCP sub-services — Gmail, Calendar, Drive, Docs, Sheets, Slides,
Chat, and People. The plugin is pure descriptor data; the runtime's connector
engine runs the OAuth flow, seals the tokens, and reaches Google's hosted MCP
servers with the connection's own token.

> [!NOTE]
>
> Google's hosted Workspace MCP servers are in **Developer Preview**. The operator
> must enroll the Cloud project in Google's Workspace Developer Preview Program and
> use their own OAuth client before these endpoints answer.

## Install

```bash theme={null}
tai plugins install tai42/connector-google \
  --env CONNECTORS_GOOGLE_CLIENT_ID=...apps.googleusercontent.com \
  --secret CONNECTORS_GOOGLE_CLIENT_SECRET
```

Or add it by hand to the manifest under `connectors:` (the descriptor block the
plugin provides):

```yaml manifest.yml theme={null}
connectors:
  - id: google
    kind: oauth
    origin: system
    category: communication
    display_name: Google
    description: Connect Gmail, Calendar, Drive, Docs, Sheets, Slides, Chat, and People.
    icon_url: https://raw.githubusercontent.com/tai42ai/tai42/main/plugins/connector-google/icon.png
    oauth:
      authorize: https://accounts.google.com/o/oauth2/v2/auth
      token: https://oauth2.googleapis.com/token
      revoke: https://oauth2.googleapis.com/revoke
    client_id_env: CONNECTORS_GOOGLE_CLIENT_ID
    client_secret_env: CONNECTORS_GOOGLE_CLIENT_SECRET
    sub_services:
      gmail:
        id: gmail
        display_name: Gmail
        scopes: [openid, email, https://www.googleapis.com/auth/gmail.readonly, https://www.googleapis.com/auth/gmail.compose]
        mcp_server: {type: http, url: https://gmailmcp.googleapis.com/mcp/v1}
    extra_authorize_params: {access_type: offline, prompt: consent, include_granted_scopes: "true"}
```

The manifest block above is trimmed to one sub-service for brevity; the plugin's
`tai-plugin.yml` carries the full set.

## Create the Google OAuth client

Create a **Web application** OAuth 2.0 client in the Google Cloud console and enable
the APIs behind the services you intend to offer (Gmail, Calendar, Drive, Docs,
Sheets, Slides, Chat, People). Enroll the Cloud project in Google's Workspace
Developer Preview Program so the hosted MCP servers accept the token.

Add this exact redirect URI, where `{origin}` is your deployment's public origin (or
`CONNECTORS_OAUTH_BRIDGE_URL` when you run a shared bridge):

```
{origin}/oauth-bridge.html
```

The path is the deployment's declared OAuth callback page, `HOSTED_UI_OAUTH_CALLBACK_PATH`
(default `/oauth-bridge.html`); a deployment that declares another path registers
`{origin}` plus that path instead.

Then set the client credentials on the API process:

```bash theme={null}
CONNECTORS_GOOGLE_CLIENT_ID=...apps.googleusercontent.com
CONNECTORS_GOOGLE_CLIENT_SECRET=...
```

The engine-wide `CONNECTORS_*` settings — the key-encryption key
(`CONNECTORS_KEK`), the state HMAC key (`CONNECTORS_STATE_HMAC_KEY`), and the
redirect-URI allowlist (or `CONNECTORS_OAUTH_BRIDGE_URL` when you run a shared
bridge) — are shared by every connector and are described in
[Connectors](/concepts/connectors). The origin you registered with Google must
appear in the redirect-URI allowlist, and it must be https for anything but a
local host.

## Services and scopes

Each service requests its own scope set, so a user consents only to what the service
they connect actually needs. Drive stays scoped to `drive.readonly` + `drive.file` —
never the full `drive` scope, which would expose the user's entire Drive.

| Service | MCP server | Scopes |
| - | - | - |
| `gmail` | `https://gmailmcp.googleapis.com/mcp/v1` | `openid`, `email`, `gmail.readonly`, `gmail.compose` |
| `calendar` | `https://calendarmcp.googleapis.com/mcp/v1` | `openid`, `email`, `calendar.calendarlist.readonly`, `calendar.events.freebusy`, `calendar.events.readonly` |
| `drive` | `https://drivemcp.googleapis.com/mcp/v1` | `openid`, `email`, `drive.readonly`, `drive.file` |
| `docs` | `https://docsmcp.googleapis.com/mcp/v1` | `openid`, `email`, `drive.readonly`, `drive.file`, `documents.readonly`, `documents` |
| `sheets` | `https://sheetsmcp.googleapis.com/mcp/v1` | `openid`, `email`, `drive.readonly`, `drive.file`, `spreadsheets.readonly`, `spreadsheets` |
| `slides` | `https://slidesmcp.googleapis.com/mcp/v1` | `openid`, `email`, `drive.readonly`, `drive.file`, `presentations.readonly`, `presentations` |
| `chat` | `https://chatmcp.googleapis.com/mcp/v1` | `openid`, `email`, `chat.spaces.readonly`, `chat.memberships.readonly`, `chat.messages.readonly`, `chat.messages.create`, `chat.users.readstate` |
| `people` | `https://people.googleapis.com/mcp/v1` | `openid`, `email`, `directory.readonly`, `userinfo.profile`, `contacts.readonly` |

All scopes above are `https://www.googleapis.com/auth/<suffix>` except `openid` and
`email`. The authorize request adds `access_type=offline`, `prompt=consent`, and
`include_granted_scopes=true`, so a refresh token comes back and previously granted
scopes are carried forward.

> [!WARNING]
>
> Several of these scopes are Google **restricted** or **sensitive** scopes
> (`gmail.readonly`, `drive.readonly`) — app verification, and for restricted scopes
> an annual third-party security assessment, are required before external users may
> consent.

## Connect an account

Each service resolves to Google's hosted Workspace MCP server, authorised with the
connection's own token. Disconnecting revokes the token at Google's revocation
endpoint.

## See also

* [Connectors](/concepts/connectors) — the model, the token lifecycle, and the shared engine settings.
* [Connect an OAuth provider](/guides/connect-an-oauth-provider) — the end-to-end walkthrough.


# Slack
Source: https://docs.tai42.ai/plugins/tai42/connector-slack

Slack OAuth connector provider for the TAI ecosystem. Pure descriptor data against Slack's hosted MCP server; ships no package.

> [!NOTE]
>
> `Connector` plugin · listing `tai42/connector-slack`

## Install

```bash theme={null}
tai plugins install tai42/connector-slack --env CONNECTORS_SLACK_CLIENT_ID=... --env CONNECTORS_SLACK_CLIENT_SECRET=... --secret CONNECTORS_SLACK_CLIENT_SECRET
```

## Permissions

| Capability | Declared |
| - | - |
| Network | no |
| Subprocess | no |
| Filesystem | no |

## Provides

### slack

`Connector` — OAuth connector for Slack over Slack's hosted MCP server.

Registers the `slack` connector: one OAuth connection per alias against Slack's
hosted MCP server at `https://mcp.slack.com/mcp`. The plugin is pure descriptor
data and ships no package; the runtime's connector engine runs the OAuth flow,
seals the tokens, and reaches the MCP server over Streamable HTTP.

## Install

Install the descriptor into the running server with the CLI:

```bash theme={null}
tai plugins install tai42/connector-slack \
  --env CONNECTORS_SLACK_CLIENT_ID=... \
  --secret CONNECTORS_SLACK_CLIENT_SECRET
```

Or add the provider by hand as a manifest `connectors:` entry:

```yaml manifest.yml theme={null}
connectors:
  - id: slack
    display_name: Slack
    description: Connect a Slack workspace over Slack's hosted MCP server.
    icon_url: https://raw.githubusercontent.com/tai42ai/tai42/main/plugins/connector-slack/icon.png
    kind: oauth
    origin: system
    category: communication
    oauth:
      authorize: https://slack.com/oauth/v2_user/authorize
      token: https://slack.com/api/oauth.v2.user.access
      revoke: null
    client_id_env: CONNECTORS_SLACK_CLIENT_ID
    client_secret_env: CONNECTORS_SLACK_CLIENT_SECRET
    sub_services:
      slack:
        id: slack
        display_name: Slack
        description: Read and post across channels, DMs, and search.
        scopes:
          - search:read
          - channels:read
          - channels:history
          - groups:read
          - groups:history
          - im:read
          - im:history
          - mpim:read
          - mpim:history
          - users:read
          - reactions:read
          - chat:write
        mcp_server:
          type: http
          url: https://mcp.slack.com/mcp
```

## Create the Slack app

Create a Slack app and configure OAuth. The app must be **directory-published or
internal** to your workspace — Slack refuses an unlisted app on this flow, and
there is no dynamic client registration. These are USER-token endpoints:

* authorize: `https://slack.com/oauth/v2_user/authorize`
* token: `https://slack.com/api/oauth.v2.user.access`

Add this exact redirect URI, where `{origin}` is your deployment's public origin
(or `CONNECTORS_OAUTH_BRIDGE_URL` when you run a shared bridge):

```
{origin}/oauth-bridge.html
```

The path is the deployment's declared OAuth callback page, `HOSTED_UI_OAUTH_CALLBACK_PATH`
(default `/oauth-bridge.html`); a deployment that declares another path registers
`{origin}` plus that path instead.

Then set the client credentials on the API process:

```bash theme={null}
CONNECTORS_SLACK_CLIENT_ID=...
CONNECTORS_SLACK_CLIENT_SECRET=...
```

The engine-wide `CONNECTORS_*` settings — the key-encryption key
(`CONNECTORS_KEK`), the state HMAC key (`CONNECTORS_STATE_HMAC_KEY`), and the
redirect-URI allowlist (or `CONNECTORS_OAUTH_BRIDGE_URL`) — are shared by every
connector and are described in [Connectors](/concepts/connectors). The origin
you registered with Slack must appear in the redirect-URI allowlist, and it must
be https for anything but a local host.

## Verify the rotating-token response (before release)

> [!WARNING]
>
> Slack's official documentation confirms this descriptor's flow: the
> `oauth.v2.user.access` endpoint returns the user token at the **top level**
> (`access_token`, `token_type: "user"`) — not nested under `authed_user` like the
> bot `oauth.v2.access` response — and `/oauth/v2_user/authorize` is the user-token
> authorize endpoint. The one detail Slack's docs do not show in an explicit
> example is the rotation-enabled response body, so before release run one manual
> Connect against a rotation-enabled Slack dev app and confirm a top-level
> `refresh_token` and `expires_in` are present, as the OAuth 2.0 spec requires.

## See also

* [Connectors](/concepts/connectors) — the model, the token lifecycle, and the shared engine settings.
* [Connect an OAuth provider](/guides/connect-an-oauth-provider) — the end-to-end walkthrough.


# identity-redis
Source: https://docs.tai42.ai/plugins/tai42/identity-redis

Redis-backed api-key identity provider for the TAI ecosystem: an installable plugin that registers itself as the "redis" identity provider (token validation plus key provisioning) over plain Redis.

> [!NOTE]
>
> `Identity` plugin · listing `tai42/identity-redis`

## Install

```bash theme={null}
tai plugins install tai42-identity-redis
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | no |

## Provides

### redis

`Identity` — Redis-backed api-key identity provider — validate inbound tokens and provision keys.

This is the default identity provider: it stores api-key hashes in Redis,
validates inbound tokens, and provisions and revokes keys. Access control is on
by default and the runtime refuses to boot with no identity provider registered,
so this plugin is the pairing every access-controlled install starts from.

## Register and select it

```yaml manifest.yml theme={null}
lifecycle_modules:
  - tai42_identity_redis.redis_api_key_provider
```

The module registers itself as the `redis` provider at import.
`ACCESS_CONTROL_AUTH_PROVIDERS` (an ordered JSON list) names the chain the verifier
tries. Unset, the chain is every registered identity provider, sorted by name.

## Configuration

The provider owns its key store, so it reads its Redis connection and key namespace
from its own `TAI_IDENTITY_` env group. The access-control gate keeps its own Redis,
`ACCESS_CONTROL_REDIS_URL`, for policies, per-user live counters and the setup token.

| Variable | Default | Effect |
| - | - | - |
| `ACCESS_CONTROL_ENABLE` | `true` | The access-control gate. Turn it off only for local, auth-free work. |
| `ACCESS_CONTROL_AUTH_PROVIDERS` | unset: every registered provider, sorted by name | Ordered provider chain the verifier tries. |
| `ACCESS_CONTROL_REDIS_URL` | unset | The gate's Redis: policies and per-user live counters. Falls back to the shared `TAI_DEFAULT_REDIS_URL`; with the gate on, one must be set. |
| `TAI_IDENTITY_REDIS_URL` | unset | Redis holding the key records. Falls back to the shared `TAI_DEFAULT_REDIS_URL`; with this provider loaded, one must be set. |
| `TAI_IDENTITY_KEY_PREFIX` | `ac:key:` | Namespace every key record carries (`<prefix><sha256 of the key>`). |
| `TAI_IDENTITY_REDIS_MAX_CONNECTIONS` | `10` | Connection pool size. |
| `TAI_IDENTITY_SOCKET_CONNECT_TIMEOUT` | `5` | Seconds to connect before the auth path fails; must be positive. |
| `TAI_IDENTITY_SOCKET_TIMEOUT` | `5` | Seconds per Redis read before the auth path fails. |
| `TAI_IDENTITY_RETRY_ON_TIMEOUT` | `true` | Retry a command that timed out. |
| `TAI_IDENTITY_RETRY_ATTEMPTS` | `0` | Retries after a first connection or timeout failure, with backoff. |
| `TAI_SETUP_TOKEN` | unset | Gate token for the one-shot `POST /api/setup` door that initializes the deployment. Unset, the platform auto-generates one and logs it once at startup; set it to pin a known value. |
| `TAI_SETUP_OPEN` | `false` | Drops the setup-token gate for local/dev. Leave off in any shared deployment. |

Any standard `redis-server` works — no RedisJSON module or `redis-stack` image is
required.

## Initialize the deployment

A fresh install has no principal and no key, and `tai keys create` authenticates
with one — so the deployment is initialized through the public, one-shot
`POST /api/setup` door. It creates the owner principal (an admin), mints the
owner's first key, and returns the raw `sk-…` key once. It is gated by a
boot-time token: set `TAI_SETUP_TOKEN`, or let the platform auto-generate one and
read it from the startup log (`setup token: …`). The door refuses with `409
Already initialized` once any principal exists.

```bash theme={null}
tai setup --display-name alice --token -
```

The raw `sk-…` owner key is printed once — capture it then. Pass `-` to read the
setup token from stdin, keeping the secret off the command line. A keys-only
install (this provider with no accounts provider) sends no login; when an
accounts provider that attaches interactive logins is configured, the owner's
login is attached in the same call.

## Provision more keys

With the owner key in hand, mint further keys the normal way — the raw `sk-…`
value is printed once.

```bash theme={null}
tai keys create --user ci --description 'CI key' --scope read
```

## See also

* [Access control](/concepts/access-control) — the policy model and the verifier chain.
* [Set up access control](/guides/access-control) — minting the first key and mapping routes to scopes.


# mcp-dynamic-postgres
Source: https://docs.tai42.ai/plugins/tai42/mcp-dynamic-postgres

Schema-driven generator for safe, scoped PostgreSQL DML tools in FastMCP agent systems

> [!NOTE]
>
> `MCP server` plugin · listing `tai42/mcp-dynamic-postgres`

## Install

```bash theme={null}
tai plugins install tai42-mcp-dynamic-postgres
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | yes |

## Provides

### mcp-dynamic-postgres

`MCP server` — Schema-driven generator for safe, scoped PostgreSQL DML tools in FastMCP agent systems

Point the server at a PostgreSQL database and it introspects the schema and
generates one typed MCP tool per DML operation per table. What the agent can reach
is set two ways that must agree: the CLI flags below decide which tools exist, and
the PostgreSQL role you connect as decides what those tools can physically do.
Connect as a dedicated least-privilege role, never a superuser.

## Connection settings

Connection and pooling come from environment variables. `PG_DB`, `PG_USER`, and
`PG_PASSWORD` have no default — a missing one fails at startup rather than
connecting with a phantom value.

| Variable | Default | Effect |
| - | - | - |
| `PG_HOST` | `localhost` | PostgreSQL host. |
| `PG_PORT` | `5432` | PostgreSQL port. |
| `PG_DB` | required | Database name. |
| `PG_USER` | required | Database user; use a least-privilege role. |
| `PG_PASSWORD` | required | Database password. Held as a secret. |
| `PG_STATEMENT_TIMEOUT` | `30000` | Per-connection `statement_timeout` in ms (`0` disables), capping a runaway query. |
| `PG_POOL_MIN_SIZE` | `1` | Minimum pooled connections. |
| `PG_POOL_MAX_SIZE` | `10` | Maximum pooled connections. |
| `PG_POOL_TIMEOUT` | `10` | Pool acquire timeout (seconds). |
| `PG_POOL_MAX_LIFETIME` | `300` | Maximum connection lifetime (seconds). |
| `TOOLS_DIR` | `~/.cache/tai42-mcp-dynamic-postgres/tools` | Where generated tool files are written. |

## Scoping flags

The flags decide which tools are generated and how permissive they are.

| Flag | Default | Effect |
| - | - | - |
| `--overwrite / --no-overwrite` | on | Regenerate tool files on startup so they track the schema; `--no-overwrite` reuses existing files. |
| `--readonly` | off | Generate only `select`/`select_joined` tools — no insert, update, or delete. |
| `--allow-unfiltered` | off | Allow `update`/`delete` to run without a `WHERE` filter (affects every row). Off means unfiltered writes raise. |
| `--select-joined a,b,c` | — | Generate a joined select over the given tables (repeatable). |
| `--ignore-insert-column` | `id` | Column to exclude from insert inputs (repeatable). |
| `--ignore-update-column` | `id` | Column to exclude from update inputs (repeatable). |
| `--ignore-select-column` | — | Column to exclude from select output models (repeatable). |
| `--ignore-select-joined-column` | — | Column to exclude from joined select models (repeatable). |
| `-t, --transport` | `stdio` | `stdio`, `http`, `sse`, or `streamable-http`. |
| `--host` | `127.0.0.1` | Bind host (HTTP/SSE transports only). |
| `--port` | `8000` | Bind port (HTTP/SSE transports only). |

## Transport

The default transport is `stdio`: an MCP client launches the server as a
subprocess and speaks over stdin/stdout. Wire it into a client's server list,
passing the connection settings through `env`:

```json theme={null}
{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": ["tai42-mcp-dynamic-postgres", "--readonly"],
      "env": { "PG_DB": "dbname", "PG_USER": "agent", "PG_PASSWORD": "secret" }
    }
  }
}
```

For a network-mounted server, choose an HTTP transport and bind a host and port
(`--host` / `--port` apply only here):

```bash theme={null}
uvx tai42-mcp-dynamic-postgres -t http --host 0.0.0.0 --port 8000
```

## Generated tools

For a table `public.events` you get (unless `--readonly`):

* `select_public_events(where, order_by, limit, offset)`
* `insert_public_events(params, raise_on_conflict)`
* `update_public_events(data, where)`
* `delete_public_events(where)`

Column types map to native Python: temporal columns to `datetime`/`date`/`time`,
`uuid` to `uuid.UUID`, `numeric`/`decimal` to `Decimal`, `json`/`jsonb` to `Any`,
and array columns to `list[...]`. `insert` returns the table's real primary key (a
scalar list for a single-column key, a list of lists for a composite key, or the
affected row count when the table has none); columns with a database default are
omittable. `order_by` items take an optional `nulls` (`FIRST`/`LAST`).

### Filtering — `WhereFilter`

`select`, `update`, and `delete` accept a `where` argument. Field names must be
real columns of the table; unknown fields are rejected, and values are always
bound parameters, so there is no path for SQL injection through field names.

```jsonc theme={null}
// Simple field filters (implicitly ANDed)
{ "status": { "eq": "open" }, "total": { "gte": 100 } }

// Logical composition
{ "AND": [ { "status": { "eq": "open" } },
           { "OR": [ { "total": { "gt": 1000 } }, { "starred": { "eq": true } } ] } ] }
```

Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `like`, `not_like`, `ilike`,
`not_ilike`, `in`, `not_in`, `between`, `is_null`, and `knn` (pgvector). Logical
keys: `AND`, `OR`, `NOT`.

### Vector search (pgvector)

When a column is a `vector`, filter or order by similarity. Requires the
`pgvector` extension enabled in the database.

```jsonc theme={null}
{ "embedding": { "knn": { "query": [0.1, 0.2, 0.3],
                          "distance": "cosine",   // l2 | inner_product | cosine
                          "threshold": 0.5 } } }
```

## Docker

```bash theme={null}
docker build -t tai42-mcp-dynamic-postgres .
docker run --rm -e PG_HOST=... -e PG_DB=... -e PG_USER=... -e PG_PASSWORD=... \
  tai42-mcp-dynamic-postgres tai42-mcp-dynamic-postgres --readonly
```


# monitoring-langfuse
Source: https://docs.tai42.ai/plugins/tai42/monitoring-langfuse

Langfuse monitoring backend for the TAI ecosystem — trace/span emission plus the observability read surface over Langfuse.

> [!NOTE]
>
> `Monitoring` plugin · listing `tai42/monitoring-langfuse`

## Install

```bash theme={null}
tai plugins install tai42-monitoring-langfuse
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | no |

## Provides

### langfuse

`Monitoring` — Langfuse monitoring backend — trace/span emission and the observability read surface.

The Langfuse monitoring backend records tool-run and agent-turn traces into a
Langfuse project — cloud or self-hosted — and the Studio reads them back through
the same interface.

Records are written by the platform's OpenTelemetry writer: each process exports
OTLP to an **OpenTelemetry collector** running as its own container, and the
collector maps the platform's attribute names onto Langfuse's and sends them to
Langfuse's OTLP endpoint. The Langfuse SDK is used for reading only (its tracing is
turned off).

## Enable it

```yaml manifest.yml theme={null}
monitoring_module: tai42_monitoring_langfuse
```

## Configuration

### The reader: the `LANGFUSE_` env group

Create a project in Langfuse Cloud or a self-hosted instance and copy its key pair
from the project settings.

| Variable | Default | Effect |
| - | - | - |
| `LANGFUSE_PUBLIC_KEY` | unset | Project public key. Required. |
| `LANGFUSE_SECRET_KEY` | unset | Project secret key. Required. Secret. |
| `LANGFUSE_HOST` | unset | Langfuse base URL — the cloud endpoint or your own instance. Required. |
| `LANGFUSE_TIMEOUT_SECONDS` | `30` | Read request timeout. |
| `LANGFUSE_TRACING_ENVIRONMENT` | `tai` | Langfuse `environment` stamped on every record (as `deployment.environment.name`), and the scope every read filters by. |

These five are the only `LANGFUSE_*` names the backend reads, and the plugin owns
the `LANGFUSE_` prefix: any other `LANGFUSE_*` name — the Langfuse SDK's own export
and debug settings (`LANGFUSE_FLUSH_AT`, `LANGFUSE_FLUSH_INTERVAL`,
`LANGFUSE_OTEL_TRACES_EXPORT_PATH`, `LANGFUSE_MEDIA_UPLOAD_ENABLED`,
`LANGFUSE_DEBUG`) or a mistyped name — refuses boot and every env write with an
error naming it. The export is tuned through the `OTEL_*` environment below and
the collector.

### The writer: the standard OpenTelemetry environment

| Variable | Required | Effect |
| - | - | - |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` (or `OTEL_EXPORTER_OTLP_ENDPOINT`) | yes | The collector's OTLP/HTTP endpoint, e.g. `http://otel-collector:4318/v1/traces`. |
| `OTEL_PYTHON_SDK_INTERNAL_METRICS_ENABLED` | yes, `true` | Turns on the span processor's own counter, through which records dropped by a full export queue are counted. |
| `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES` | no | The resource every record carries. |
| `OTEL_BSP_MAX_QUEUE_SIZE` / `OTEL_BSP_SCHEDULE_DELAY` / `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` | no | Export queue and batching (SDK defaults 2048 / 5000 ms / 512). |
| `OTEL_EXPORTER_OTLP_TRACES_TIMEOUT`, `…_COMPRESSION`, `…_HEADERS` | no | The exporter's request options. |
| `OTEL_METRIC_EXPORT_INTERVAL` | no | How often the queue-drop count is collected (default 60000 ms); every flush collects it too. |

`OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` and `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT`
have no effect: the writer never truncates a recorded value.

### The collector

The collector holds the backend credential, named outside the `LANGFUSE_` prefix:
`OTEL_COLLECTOR_LANGFUSE_AUTH` is the base64 of `public_key:secret_key`, sent as
`Authorization: Basic …` to `${LANGFUSE_HOST}/api/public/otel`. Its pipeline maps
the platform's `tai42.trace.*`, `tai42.run.version`, `tai42.level`,
`tai42.status_message`, `tai42.span.kind` and `tai42.usage.cost_usd` attributes onto
Langfuse's names; GenAI messages, tool arguments and results, and chain inputs and
outputs use the OpenTelemetry names Langfuse reads natively. Its sending queue lives
on a volume and retries until delivered.

> [!WARNING]
>
> Selecting `monitoring_module` without the three required `LANGFUSE_*` keys, without
> an OTLP endpoint, or without `OTEL_PYTHON_SDK_INTERNAL_METRICS_ENABLED=true` raises
> at startup, naming what is missing — a monitoring backend that silently drops traces
> is worse than a server that will not boot. To run without monitoring, omit
> `monitoring_module` entirely; the runtime falls back to a built-in no-op.

## Share one project between deployments

`LANGFUSE_TRACING_ENVIRONMENT` both stamps records and scopes reads, so several
deployments can share one Langfuse project by diverging on it — staging and
production write into the same project and each reads only its own traces.
Reading a trace or an observation by id is unscoped, because ids are globally
unique.

## Run attribution and data retention

The platform tags each run's trace with generic identity at its shared
chokepoints, and the collector maps them onto Langfuse's native trace
dimensions: `user_id`, `session_id`, `version`, and `tags` — so runs are
filterable and groupable by exactly those, including from the observability
`user` / `session` / `meta.<key>` query params.

`user_id` is **person-id-first**: a run with a resolved person is attributed by
that person's stable `person_id`. With no person it falls back to the raw
`{channel}:{client_address}` the door saw (an end-user address), or, on the API
door where no channel exists, the bare `client_address`. Treat these as personal
data.

> [!WARNING]
>
> That identity lands in **your** Langfuse project, so it is yours to govern. Set a
> deliberate retention policy — Langfuse keeps traces until you delete them; the
> platform sets none on your behalf. Honour erasure by deleting a subject's traces
> keyed on their `user_id` (the `person_id`, or the raw address for an unlinked
> subject); person-id-first keeps a linked subject's cross-channel history under
> one deletable key.

## Quirks

* The package pins the Langfuse SDK to a narrow range for its read API. Upgrading
  the Langfuse **server** is safe; changing the pinned SDK is not.
* A self-hosted Langfuse is a standalone stack (its own Postgres, ClickHouse,
  Redis, and object store); the collector and the reader both reach it at
  `LANGFUSE_HOST`.

## See also

* [Observe](/operate/observe) — metrics, traces, the collector, and what the runtime emits.


# sandbox-docker
Source: https://docs.tai42.ai/plugins/tai42/sandbox-docker

Docker sandbox provider for the TAI ecosystem — per-session containers on a remote engine over the Docker Engine API.

> [!NOTE]
>
> `Sandbox` plugin · listing `tai42/sandbox-docker`

## Install

```bash theme={null}
tai plugins install tai42-sandbox-docker
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | no |

## Provides

### docker

`Sandbox` — Docker sandbox provider — per-session containers on a remote engine over the Docker Engine API.

The Docker sandbox provider runs each session as its own container on a REMOTE
Docker engine, reached over the Docker Engine API. The app container drives that
engine over mTLS: it spawns no local process, holds no host Docker socket, and
mounts no host path. Real work in a session is driven through the engine's exec
API against a hardened, idle session container.

## Enable it

```yaml manifest.yml theme={null}
sandbox_module: tai42_sandbox_docker
```

## Configuration

The `SANDBOX_DOCKER_` env group. The mTLS client certificates are read from files,
by default on the canonical `/certs/client` mount. The environment carries only the
file paths, never the certificate or key material — the one channel a client
identity must never leak through. Every knob below is ordinary env.

| Variable | Default | Effect |
| - | - | - |
| `SANDBOX_DOCKER_HOST` | required | The remote engine: a `unix:///var/run/...` socket path or a `tcp://host:port`. No default — a mis-wired deployment fails loudly at first use. |
| `SANDBOX_DOCKER_TLS_VERIFY` | `true` | Verify the engine over mTLS for a `tcp://` host. An unauthenticated `tcp://` endpoint is never the documented shape. |
| `SANDBOX_DOCKER_TLS_CERT_PATH` | `/certs/client/cert.pem` | The mTLS client certificate that speaks the engine control API. |
| `SANDBOX_DOCKER_TLS_KEY_PATH` | `/certs/client/key.pem` | The mTLS client key. |
| `SANDBOX_DOCKER_TLS_CA_PATH` | `/certs/client/ca.pem` | The CA that anchors the engine's server certificate. |
| `SANDBOX_DOCKER_DEFAULT_CPU` | unset | Fallback CPU cap (cores) applied only when a session spec leaves `cpu` unset. |
| `SANDBOX_DOCKER_DEFAULT_MEMORY_MB` | unset | Fallback memory cap (MiB) applied only when a session spec leaves `memory_mb` unset. |
| `SANDBOX_DOCKER_PULL_POLICY` | `missing` | `missing` pulls an image only when absent; `never` refuses to pull (airgapped) and a missing image raises. |
| `SANDBOX_DOCKER_REAP_INTERVAL_SECONDS` | `300` | Sweep interval of the platform reaper while this provider is bound. |
| `SANDBOX_DOCKER_EXEC_DEFAULT_TIMEOUT_SECONDS` | `300` | Timeout bounding a consumer's short exec that names none (e.g. the deep agent's file operations). |
| `SANDBOX_DOCKER_READINESS_PROBE_ENABLED` | `false` | Prove the engine's egress firewall is in force on every session create, and refuse the create loudly when it cannot. Opt-in — leave off for a `unix://` dev engine or a non-firewalled deployment. |
| `SANDBOX_DOCKER_READINESS_PROBE_IMAGE` | `busybox:latest` | The throwaway probe container's image — a busybox-family image carrying `nc`. Ensured under `SANDBOX_DOCKER_PULL_POLICY`, so `never` refuses to pull an absent probe image. |
| `SANDBOX_DOCKER_READINESS_PROBE_TIMEOUT_SECONDS` | `30.0` | Bound on the whole probe; on expiry the create is refused (the engine is not provably ready in time). |

A session spec's `cpu` / `memory_mb` always win over the defaults; the provider
never silently runs uncapped when a cap was requested, and rejects a cap it
cannot express rather than downgrading it.

## Security model

* **Remote engine over mTLS.** The app container talks to a remote engine; it
  never holds a host Docker socket and never runs privileged.
* **Per-session containers, hardened.** Every session container is created with
  `no-new-privileges`, all Linux capabilities dropped, never privileged, and no
  host bind mount of any path.
* **Single-workspace-mount isolation invariant.** A session container mounts ONLY
  its own workspace volume — never the engine client-certs volume, never a host
  path — so a session can never read the mTLS client identity that speaks the
  control API.
* **Network tiers.** `none` attaches no network beyond loopback; `internal` joins
  an isolated bridge with no external routing; `egress` joins the engine's NAT'd
  bridge with the public internet reachable. Egress default is OPEN.
* **Honest residual.** Under open egress, tool-RESULT data a session produces is
  exfiltratable — egress is default-open by design. The egress firewall that
  drops the control plane, RFC1918 ranges, and cloud metadata is provisioned at
  the tai-distribution layer, not by this provider.
* **Egress-firewall readiness (opt-in).** With
  `SANDBOX_DOCKER_READINESS_PROBE_ENABLED`, a create first PROVES that engine's
  egress firewall is in force: a throwaway, unprivileged probe container on the
  egress tier must NOT reach the engine control address it must drop and MUST reach
  its own DNS resolver, or the create is REFUSED loudly — never a session on an
  unconfined engine. It is defense in depth for the window an engine restart opens
  under a running app; both probe targets are DERIVED (the configured engine address
  and the probe's own resolver), so there is no target to mis-set.

## Durability model

* **Ephemeral** sessions get an anonymous workspace volume that is reaped with the
  session — scratch that dies with it.
* **Persistent** sessions bind a named `tai-sbx-<workspace_key>` volume that
  survives the session and its reap. Only an explicit teardown removes it, and even
  then unforced, so the engine's own "volume in use" guard blocks removal while
  another worker still references it.

The persistent store is backed by REAL block storage provisioned at the
tai-distribution layer (a named docker volume on compose). If
that layer does not present durable, node-independent volume storage, a persistent
session's data does not actually survive a node move. See the tai-docs operate page
for the deployment topology.


# sandbox-local
Source: https://docs.tai42.ai/plugins/tai42/sandbox-local

Direct/host sandbox provider for the TAI ecosystem — runs a session's code as a plain host subprocess, no container and no isolation.

> [!NOTE]
>
> `Sandbox` plugin · listing `tai42/sandbox-local`

## Install

```bash theme={null}
tai plugins install tai42-sandbox-local
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | yes |
| Filesystem | yes |

## Provides

### local

`Sandbox` — Direct/host sandbox — runs the session's code as a host subprocess, no isolation.

The local sandbox runs a session's code **directly on the host** as a plain
subprocess. There is no container and no isolation: the operator picks this
execution mode by installing this provider instead of a container provider, and
every consumer acquires it through the same provider-agnostic seam.

## Enable it

```yaml manifest.yml theme={null}
sandbox_module: tai42_sandbox_local
```

## Configuration

The `SANDBOX_LOCAL_` env group.

| Variable | Default | Effect |
| - | - | - |
| `SANDBOX_LOCAL_ROOT` | `/var/lib/tai-sandbox-local` | Host workspace root. A persistent session's workspace is the named directory `<SANDBOX_LOCAL_ROOT>/<workspace_key>`. Changing it strands existing durable workspaces (recycle-class). |
| `SANDBOX_LOCAL_BASE_PATH` | `/usr/local/bin:/usr/bin:/bin` | The `PATH` seeded into the clean subprocess env so a host subprocess resolves its binary without inheriting the host environment. A `spec.env` / per-exec `env` `PATH` overrides it. |
| `SANDBOX_LOCAL_REAP_INTERVAL_SECONDS` | `300` | Sweep interval of the platform reaper while this provider is bound. |
| `SANDBOX_LOCAL_EXEC_DEFAULT_TIMEOUT_SECONDS` | `300` | Timeout bounding a consumer's short exec that names none (e.g. the deep agent's file operations). |

## Security model — read this honestly

This provider gives **no isolation**. `isolation="none"` means arbitrary session
code runs on the host with the host's filesystem, network, and any host-reachable
secrets in reach. That is the accepted price of the direct mode: fine for a
**trusted, single-tenant box** the operator controls, **not** for untrusted flows.
For enforced isolation, install a container provider instead.

* **Isolation floor.** Only `isolation="none"` is accepted. A `container` / `vm`
  request is rejected loudly — this provider never silently downgrades a stronger
  request to a bare host process. Because the operator isolation floor defaults to
  `container`, a deployment that installs this provider **must** set
  `TAI_MCP_SANDBOX_ISOLATION=none`; otherwise every session create rejects. That
  coupling is deliberate: dropping isolation is an explicit operator choice, never
  reached by accident.
* **Network.** Only `network="egress"` is truthful — a host subprocess runs on the
  host network. `none` / `internal` are rejected, because a bare host process
  cannot be confined without machinery this mode omits. Use a container provider
  for network lockdown.
* **Resource caps.** A `cpu` / `memory_mb` cap is rejected — the direct mode has no
  cgroup/rlimit machinery and never runs a capped request uncapped.
* **`image` is inert.** The host itself is the execution environment; the operator
  installs the runtime on the host. The requested image reference is surfaced on
  `info()` / `list_sessions()` and recorded in the workspace's sidecar metadata for
  traceability, but never governs the runtime. An operator who needs a pinned image
  to actually govern the runtime uses a container provider.

## Durability

* **Persistent** — the named directory `<SANDBOX_LOCAL_ROOT>/<workspace_key>`,
  created-if-absent / adopted-if-present. It survives the session and a reap; only
  an explicit teardown removes it. This is the durable workspace persistent
  sessions share by `workspace_key`.
* **Ephemeral** — a fresh temp directory under `<SANDBOX_LOCAL_ROOT>/.ephemeral/`,
  removed on reap and on destroy. Scratch that dies with the session.

Whether a persistent workspace survives a **node move** depends on the storage
under `SANDBOX_LOCAL_ROOT`: it must be durable, node-independent storage, or a
persistent session's data does not actually survive the move. (Direct/host mode is
typically a single-box deployment where the box's own disk is that storage.)

### Cross-worker teardown

The session ledger is per process: one app worker cannot see that another holds a
live session over the same persistent directory, and a plain host directory has no
kernel "in use" refusal. So a reap never removes a persistent directory
(`remove_workspace=False`), and an explicit teardown that does remove it is a
deliberate operation the consumer issues outside a live turn — guarded by the
consumer's per-`workspace_key` lease (the same lease that serializes turns), not by
a filesystem lock.

## Host runtime

This provider ships **no runtime**: it simply execs whatever `argv` the consumer
hands it. If a consumer needs a host runtime present, the operator installs it on
the host. See the platform operate page for the deployment prerequisites.


# storage-github
Source: https://docs.tai42.ai/plugins/tai42/storage-github

GitHub-backed Storage provider (text + binary/media) for the TAI ecosystem.

> [!NOTE]
>
> `Storage` plugin · listing `tai42/storage-github`

## Install

```bash theme={null}
tai plugins install tai42-storage-github
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | no |

## Provides

### github

`Storage` — Storage backend serving text and binary/media content over a GitHub repository.

Stores content as files on a branch of a GitHub repository, which makes every write
a commit and every version reviewable. Select it in the manifest:

```yaml manifest.yml theme={null}
storage_module: tai42_storage_github
```

## Configuration

| Variable | Default | Effect |
| - | - | - |
| `STORAGE_GITHUB_USERNAME` | unset | Repository owner — a user or an organisation. Required. |
| `STORAGE_GITHUB_REPO` | unset | Repository name. Required. |
| `STORAGE_GITHUB_BRANCH` | `main` | Branch read and written. |
| `STORAGE_GITHUB_TOKEN` | unset | Access token. Omit only for a public repository, which is then read-only in practice. |
| `STORAGE_GITHUB_TIMEOUT_TOTAL` | `15.0` | Total HTTP timeout in seconds. |
| `STORAGE_GITHUB_MAX_CONNECTIONS` | `200` | Connection-pool ceiling. |
| `STORAGE_GITHUB_MAX_KEEPALIVE_CONNECTIONS` | `50` | Keep-alive pool size. |
| `STORAGE_GITHUB_KEEPALIVE_EXPIRY` | `300.0` | Keep-alive expiry in seconds. |

## Token scopes

A fine-grained token needs **Contents: read and write** on the repository; a classic
token needs `repo`. Only `STORAGE_GITHUB_TOKEN` is read — an ambient `GITHUB_TOKEN`
is ignored, as are proxy environment variables.

## Quirks

> [!WARNING]
>
> Two limits shape what this provider suits. Writes are capped at 1 MiB and a larger
> payload raises before the request. Reads come from the raw content CDN, which can
> serve a stale copy for a few minutes after a write — do not use GitHub storage for
> content a tool writes and immediately reads back.

Listing uses the recursive tree API and raises on a truncated response rather than
acting on a partial listing. The API host is fixed, so GitHub Enterprise Server is
not supported.

## See also

* [Storage and resources](/concepts/storage-and-resources) — the ResourceManager contract this provider backs.
* [Manage stored content](/guides/manage-stored-content) — the day-to-day commands.


# storage-local
Source: https://docs.tai42.ai/plugins/tai42/storage-local

Local-filesystem storage backend for the TAI ecosystem: a manifest-loaded Storage plugin serving text and binary content from a directory tree.

> [!NOTE]
>
> `Storage` plugin · listing `tai42/storage-local`

## Install

```bash theme={null}
tai plugins install tai42-storage-local
```

## Permissions

| Capability | Declared |
| - | - |
| Network | no |
| Subprocess | no |
| Filesystem | yes |

## Provides

### local

`Storage` — Storage backend serving text and binary content from a local directory tree.

Names one directory on the server's own disk as the active storage provider. Every
stored path resolves under one root, and a path that escapes it raises rather than
reading outside.

Select it in the manifest:

```yaml manifest.yml theme={null}
storage_module: tai42_storage_local
```

## Configuration

| Variable | Default | Effect |
| - | - | - |
| `STORAGE_LOCAL_ROOT_PATH` | required | The base directory every stored path resolves under; every call refuses until it is set. A relative path resolves against the process working directory. |
| `STORAGE_LOCAL_CREATE_DIRS` | `true` | Create parent directories on write. |

The root has no default: until `STORAGE_LOCAL_ROOT_PATH` is set, every storage call, `list` included,
raises `RuntimeError`, so an unmounted or mistyped location never reads as an empty store. Set
`STORAGE_LOCAL_ROOT_PATH=./templates` to keep files under the working directory's `templates/`.

## Quirks

Content types are inferred from the path suffix, because a filesystem records none.

> [!WARNING]
>
> Local storage is per-process state on one machine's disk. A multi-replica fleet
> gives each replica its own copy — use S3 or GitHub instead.

## See also

* [Storage and resources](/concepts/storage-and-resources) — the ResourceManager contract this provider backs.
* [Manage stored content](/guides/manage-stored-content) — the day-to-day commands.


# storage-s3
Source: https://docs.tai42.ai/plugins/tai42/storage-s3

S3 storage backend for the TAI ecosystem — text, binary, and media content over an S3 bucket.

> [!NOTE]
>
> `Storage` plugin · listing `tai42/storage-s3`

## Install

```bash theme={null}
tai plugins install tai42-storage-s3
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | no |

## Provides

### s3

`Storage` — Storage backend serving text, binary, and media content over an S3 bucket.

Backs stored content with any S3-compatible bucket, including MinIO. Select it in
the manifest:

```yaml manifest.yml theme={null}
storage_module: tai42_storage_s3
```

## Configuration

| Variable | Default | Effect |
| - | - | - |
| `STORAGE_S3_BUCKET` | unset | Target bucket. The first operation raises when it is unset. |
| `STORAGE_S3_ENDPOINT` | unset (AWS) | Custom endpoint for MinIO or another S3-compatible service. |
| `STORAGE_S3_ACCESS_KEY` | unset | Access key id. |
| `STORAGE_S3_SECRET_KEY` | unset | Secret access key. |
| `STORAGE_S3_REGION` | `us-east-1` | Region name. |
| `STORAGE_S3_SECURE` | `true` | Use TLS, and pick the scheme for a schemeless endpoint. |
| `STORAGE_S3_VERIFY_SSL` | `true` | Verify the endpoint's certificate. |
| `STORAGE_S3_ADDRESSING_STYLE` | `auto` | `path`, `virtual`, or `auto`. MinIO usually needs `path`. |
| `STORAGE_S3_CONNECT_TIMEOUT` | `5` | Connect timeout in seconds. |
| `STORAGE_S3_READ_TIMEOUT` | `30` | Read timeout in seconds. |
| `STORAGE_S3_REQUEST_CHECKSUM_CALCULATION` | unset | `when_supported` or `when_required`, for S3-compatible services that reject the AWS default. |
| `STORAGE_S3_CHECKSUM_ALGORITHM` | unset | Request-body checksum algorithm — `CRC32`, `CRC32C`, `SHA1`, `SHA256`, or `CRC64NVME`. Unset keeps botocore's CRC32 default; set one the store accepts (e.g. `SHA256`) for an S3-compatible store that refuses CRC32. `CRC32C` and `CRC64NVME` require the `botocore[crt]` extra. |

Leave the key pair unset to fall through to the AWS credential chain — an instance
profile, IRSA, or `~/.aws/credentials`.

## Bucket policy

The bucket policy needs `s3:GetObject`, `s3:PutObject`, `s3:DeleteObject`, and
`s3:ListBucket` on the bucket and its contents. The driver's `HeadObject` probes
fall under `s3:GetObject` and its multi-object delete under `s3:DeleteObject`; it
makes no other calls.

## Content types

`upload` (text) stores `ContentType: text/plain; charset=utf-8`; `stat` on a text object reports it.

## See also

* [Storage and resources](/concepts/storage-and-resources) — the ResourceManager contract this provider backs.
* [Manage stored content](/guides/manage-stored-content) — the day-to-day commands.


# toolbox
Source: https://docs.tai42.ai/plugins/tai42/toolbox

Reference contrib package for the TAI ecosystem: opt-in, manifest-loaded generic tools and tool extensions (a tool extension extends a single tool).

> [!NOTE]
>
> `Tool` plugin · listing `tai42/toolbox`

## Install

```bash theme={null}
tai plugins install tai42-toolbox
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | no |

## Provides

### classify

`Tool` — Judge JSON state against typed questions and return typed answers.

### current\_time\_info

`Tool` — Return the current time as a structured object.

### generate\_embeddings

`Tool` — Generate embeddings for a single string or a list of strings.

### generate\_uuid

`Tool` — Generate a random UUID (version 4).

### pad\_embeddings

`Tool` — Pad each embedding vector with zeros up to a target dimension.

### request

`Tool` — Execute an HTTP request through a curl-backed session.

### batch

`Extension` · group `extensions` — Branch a tool into a variant that runs many instances at once.

### cache

`Extension` · group `extensions` — Branch a tool into a variant that memoizes results by call arguments.

### chain

`Extension` · group `extensions` — Branch a tool into a variant that transforms its output and calls a next tool.

### output\_schema

`Extension` · group `extensions` — Branch a tool into a variant that forces a configured JSON Schema as its output schema and validates every result against it.

### prometheus\_metrics

`Extension` · group `extensions` — Branch a tool into a variant that records a Prometheus call metric.

### proxy

`Extension` · group `extensions` — Branch a tool into a variant that runs the wrapped tool through a proxy.

The standard toolbox: six general-purpose tools and six tool extensions, each loaded
by name into a manifest. The tool-and-extension model and the day-to-day guide stay
central (linked below); this page is the per-item index and the extension settings.

## Install extras

The base install stays light: a module with a heavy dependency needs its package extra.
A module whose extra is missing fails loudly with the install hint, for example
`pip install 'tai42-toolbox[prometheus]'`.

| Module | Extra |
| - | - |
| `request` | `http` |
| `classify` | `classifier` |
| `generate_embeddings` | `embeddings` |
| `chain` | `chain` |
| `prometheus_metrics` | `prometheus` |
| `proxy` (SOCKS proxies only; HTTP and HTTPS proxies need none) | `proxy` |

## Tools

### classify

Judges JSON state against typed questions — yes/no, pick one, rate — and returns typed answers with probabilities.

### current\_time\_info

Returns the current time as a structured object.

### generate\_embeddings

Generates embeddings for a single string or a list of strings.

### generate\_uuid

Generates a random UUID (version 4).

### pad\_embeddings

Pads each embedding vector with zeros up to a target dimension.

### request

Executes an HTTP request through a curl-backed session.

## Extensions

Each extension branches a tool into a variant; attach one through a manifest's
`extensions` map.

### batch

Branches a tool into a variant that runs many instances at once. The extension declares
that its branches can pause (`pauses=True`): an instance that parks surfaces its park
through the batch variant.

| Variable | Default | Effect |
| - | - | - |
| `BATCH_DEFAULT_MAX_CONCURRENT` | `5` | Concurrency for a parallel call that names no `max_concurrent`, floored to the input size. |
| `BATCH_MAX_BATCH_SIZE` | `100` | Hard ceiling on the params per call; an over-limit call raises loudly. |

### cache

Branches a tool into a variant that memoizes results by call arguments.

| Variable | Default | Effect |
| - | - | - |
| `CACHE_MAX_ENTRIES` | `1024` | Live entries a single cache branch retains before evicting LRU. |

### chain

Branches a tool into a variant that transforms its output and calls a next tool. The
extension declares that its branches can pause (`pauses=True`): a stage that parks surfaces
its park through the chain variant.

### output\_schema

Branches a tool into a variant that forces a configured JSON Schema as its output
schema and validates every result against it.

### prometheus\_metrics

Branches a tool into a variant that records a Prometheus call metric.

### proxy

Branches a tool into a variant that runs the wrapped tool through a proxy.

| Variable | Default | Effect |
| - | - | - |
| `PROXY_POOL` | empty | Proxy URLs the pool routes over. |
| `PROXY_ALLOW_CALLER_URLS` | `false` | Whether a caller may supply its own proxy URL. |
| `PROXY_CONNECT_TIMEOUT` | `30` | Connect timeout in seconds; must be positive. |

## See also

* [Tools and extensions](/concepts/tools-and-extensions) — the model.
* [Standard toolbox](/guides/standard-toolbox) — the day-to-day guide.


# tools-github
Source: https://docs.tai42.ai/plugins/tai42/tools-github

GitHub provisioning tools for the TAI ecosystem: manifest-loaded repository-webhook setup tools that create a repository webhook, list a repository's webhooks with Link-header pagination, and delete a repository webhook — the provider-side counterpart to the runtime signature verifier.

> [!NOTE]
>
> `Tool` plugin · listing `tai42/tools-github`

## Install

```bash theme={null}
tai plugins install tai42-tools-github
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | no |

## Provides

### create\_github\_webhook

`Tool` — Create a repository webhook and return its id, url, events, and active flag.

### list\_github\_webhooks

`Tool` — List a repository's webhooks, following Link-header pagination to exhaustion.

### delete\_github\_webhook

`Tool` — Delete a repository webhook by id.

Three tools that provision a GitHub repository's webhooks over the REST API: create a
webhook, list a repository's webhooks, and delete one. They are the provider-side setup
counterpart to a runtime webhook-signature verifier — the tools register the hook a
verifier later authenticates.

## Configuration

| Variable | Default | Effect |
| - | - | - |
| `TOOLS_GITHUB_TOKEN` | unset | GitHub token (`Authorization: Bearer`). Missing or empty raises on every tool call. |
| `TOOLS_GITHUB_API_BASE` | `https://api.github.com` | GitHub REST API origin. Privileged — receives the `Authorization` header. |
| `TOOLS_GITHUB_REQUEST_TIMEOUT_SECONDS` | `20` | Per-request HTTP timeout in seconds. |

The token needs the scope GitHub requires to administer repository webhooks (the
`admin:repo_hook` scope on a classic token, or repository `Webhooks` read/write on a
fine-grained token). A missing or empty token raises loudly (fails closed) — never a
silently-unauthenticated request.

## create\_github\_webhook

Creates a repository webhook on `owner/name` and returns its id, delivery url, events and
active flag. GitHub does not mint the signing secret: the caller supplies it, GitHub keys
`X-Hub-Signature-256` with it, and the caller keeps its own copy — GitHub never returns
it and the tool never echoes it.

## list\_github\_webhooks

Lists every webhook on `owner/name`, following the `Link` response header to exhaustion,
and returns each hook's id, delivery url, events and active flag. GitHub never returns a
hook's secret.

## delete\_github\_webhook

Deletes the webhook `hook_id` from `owner/name`. Succeeds only on GitHub's `204`; an
unknown hook (404) or any other non-2xx raises, never a silent success.


# tools-stripe
Source: https://docs.tai42.ai/plugins/tai42/tools-stripe

Stripe payment tools for the TAI ecosystem: manifest-loaded tools for the external-ask checkout link, the webhook-bridge confirm, the reconciliation recovery layer, a flexible-amount non-blocking payment link, an early expire of an issued checkout session, and webhook-endpoint provisioning (create, list, delete).

> [!NOTE]
>
> `Tool` plugin · listing `tai42/tools-stripe`

## Install

```bash theme={null}
tai plugins install tai42-tools-stripe
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | no |

## Provides

### confirm\_stripe\_payment

`Tool` · group `payment-confirm` — Answer a paid checkout ask from a Stripe webhook event.

### create\_stripe\_checkout

`Tool` · group `payment-sessions` — Create a Stripe Checkout Session and return its hosted payment URL.

### create\_stripe\_payment\_link

`Tool` · group `payment-sessions` — Create a flexible-amount non-blocking Stripe payment link and return its URL and session id.

### create\_stripe\_webhook\_endpoint

`Tool` · group `webhook-endpoints` — Create a Stripe webhook endpoint and return its id and one-time signing secret.

### delete\_stripe\_webhook\_endpoint

`Tool` · group `webhook-endpoints` — Delete a Stripe webhook endpoint by id.

### expire\_stripe\_checkout

`Tool` · group `payment-sessions` — Expire an open Stripe Checkout Session early and return its id and status.

### list\_stripe\_webhook\_endpoints

`Tool` · group `webhook-endpoints` — List the account's Stripe webhook endpoints (no signing secrets).

### reconcile\_stripe\_payments

`Tool` · group `payment-confirm` — Re-answer paid Stripe checkout sessions the webhook path may have lost.

Eight tools: four that take a payment through Stripe Checkout and reconcile the result
back to a blocked interaction, one that expires an open checkout session early, and three
that provision the account's webhook endpoints.
The full deployment — the money-pinning preset, the manifest
wiring, the verifier binding, the reconciliation schedule, and the confused-deputy
rules that make it safe to hand an agent — is a guide that stays central; see
[Use interactions](/guides/use-interactions). This page is the
per-tool index and the settings.

## Configuration

| Variable | Default | Effect |
| - | - | - |
| `STRIPE_SECRET_KEY` | unset | Stripe secret or restricted key. Missing or empty raises on every tool call. |
| `STRIPE_API_BASE` | `https://api.stripe.com` | Stripe API origin. |
| `STRIPE_REQUEST_TIMEOUT_SECONDS` | `20` | Per-request HTTP timeout in seconds. |
| `STRIPE_RECONCILE_ANSWER_INTERVAL_SECONDS` | `1.2` | Serial pacing between answers in a reconciliation run, so a batch does not burst the callback door. |

Two further values are read under their unprefixed platform names, shared with the
rest of the deployment: `TAI_BRIDGE_CALLBACK_SECRET` (signs the answer the tools post
back) and `INTERACTIONS_PUBLIC_BASE_URL` (read by the platform, which mints the callback
URL every answer POST is pinned to). Both must be present on every process — app and worker —
that runs these tools.

The tools reject a session whose `livemode` disagrees with the configured key's mode,
so a worker's key must be the same mode (`sk_live_`/`rk_live_` vs `sk_test_`/`rk_test_`)
as the app's.

## confirm\_stripe\_payment

Answers a paid checkout ask from a Stripe webhook event. Bound to a payments topic
through a hook so the signed `checkout.session.completed` delivery answers the blocked
caller.

## create\_stripe\_checkout

Creates a Stripe Checkout Session and returns its hosted payment URL. Compose it with
the `ask_external` extension to open a blocking payment ask.

## create\_stripe\_payment\_link

Creates a flexible-amount, non-blocking Stripe payment link and returns its URL and
session id.

## create\_stripe\_webhook\_endpoint

Provisions a Stripe webhook endpoint for an `https` URL and a set of event types, and returns
its id and one-time signing secret. Stripe reveals the secret only at creation, so this tool
returns it to the caller and persists it nowhere; storing it is the caller's job. Stripe has no
rotate-secret endpoint — rotation is create-new, swap-config, delete-old.

## delete\_stripe\_webhook\_endpoint

Deletes a Stripe webhook endpoint by id and returns Stripe's deletion confirmation.

## expire\_stripe\_checkout

Expires an `open` Checkout Session early — before Stripe's \~24h default timeout — and
returns its id and post-expire status. A completed or already-expired session is a Stripe
400 that propagates, never a silent success.

## list\_stripe\_webhook\_endpoints

Lists the account's webhook endpoints with their id, url, status and events. Stripe never
returns a signing secret post-creation.

## reconcile\_stripe\_payments

Re-answers any paid Stripe checkout session whose webhook never arrived, or whose
hook run is held as failed, by listing recent sessions from Stripe and answering each
through the same pinned bridge path. Run it on a schedule as the recovery layer for payments.

## See also

* [Use interactions](/guides/use-interactions) — the full Stripe payments deployment, in order.
* [Triggers and webhooks](/concepts/triggers-and-webhooks) — the verifier that authenticates the signed callback.


# tools-twilio
Source: https://docs.tai42.ai/plugins/tai42/tools-twilio

Twilio provisioning tools for the TAI ecosystem: manifest-loaded REST tools that list a Twilio account's incoming phone numbers, read a number's inbound-message webhook, and set a number's inbound-message webhook URL.

> [!NOTE]
>
> `Tool` plugin · listing `tai42/tools-twilio`

## Install

```bash theme={null}
tai plugins install tai42-tools-twilio
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | no |

## Provides

### list\_twilio\_numbers

`Tool` — List a Twilio account's incoming phone numbers with their inbound-message webhook.

### get\_twilio\_number\_webhook

`Tool` — Read one Twilio number's inbound-message webhook URL and method.

### set\_twilio\_number\_webhook

`Tool` — Set a Twilio number's inbound-message webhook to a given https URL.

Three tools that provision a Twilio phone number's inbound-message webhook over
Twilio's REST API: list the account's numbers, read one number's webhook, and set
a number's webhook URL. They configure the number so an inbound message reaches
the platform; the message-handling channel is a separate concern.

## Configuration

The tools read the same `CHANNEL_TWILIO_` credentials as the deployment's Twilio
channel — one account SID, auth token, and REST base configure both.

| Variable | Default | Effect |
| - | - | - |
| `CHANNEL_TWILIO_ACCOUNT_SID` | unset | Twilio account SID. Missing or empty raises on every tool call. |
| `CHANNEL_TWILIO_AUTH_TOKEN` | unset | Twilio auth token. Missing or empty raises on every tool call. |
| `CHANNEL_TWILIO_API_BASE_URL` | `https://api.twilio.com/2010-04-01` | Twilio REST origin (carries the API version prefix). |
| `CHANNEL_TWILIO_HTTP_TIMEOUT_SECONDS` | `30` | Per-request HTTP timeout in seconds. |

Credentials live only in the environment. A request carries HTTP Basic auth
(`AccountSid:AuthToken`); the auth header is never echoed into a raised error, and
redirects are not followed so it cannot reach another host.

## list\_twilio\_numbers

Lists every incoming phone number on the account, following Twilio's paging to
exhaustion, and returns each number's `sid`, `phone_number`, `sms_url`, and
`sms_method`.

## get\_twilio\_number\_webhook

Reads one number's inbound-message webhook. Takes the number's `phone_number_sid`
(required, non-empty) and returns its `sid`, `phone_number`, `sms_url`, and
`sms_method`.

## set\_twilio\_number\_webhook

Points a number's inbound-message webhook at a URL. Takes `phone_number_sid`
(required, non-empty) and `sms_url` (required, non-empty, https) and returns the
updated `sid`, `phone_number`, and `sms_url`. A non-https or empty URL raises
before any network call; a Twilio non-2xx propagates unchanged.


# tools-whatsapp
Source: https://docs.tai42.ai/plugins/tai42/tools-whatsapp

WhatsApp provisioning tools for the TAI ecosystem: manifest-loaded Meta Graph tools that register a WhatsApp message template, list the account's message templates, delete a message template by name, and subscribe the app to a WhatsApp Business Account's webhooks.

> [!NOTE]
>
> `Tool` plugin · listing `tai42/tools-whatsapp`

## Install

```bash theme={null}
tai plugins install tai42-tools-whatsapp
```

## Permissions

| Capability | Declared |
| - | - |
| Network | yes |
| Subprocess | no |
| Filesystem | no |

## Provides

### register\_whatsapp\_template

`Tool` · group `message-templates` — Register a WhatsApp message template on the business account and return Graph's id and status.

### list\_whatsapp\_templates

`Tool` · group `message-templates` — List every WhatsApp message template on the business account, following Graph's paging to exhaustion.

### delete\_whatsapp\_template

`Tool` · group `message-templates` — Delete a WhatsApp message template by name and return Graph's response.

### subscribe\_whatsapp\_app

`Tool` — Subscribe the app to the business account's webhooks, optionally overriding the callback URI and verify token, and return Graph's response.

Four tools that provision a WhatsApp Business Account through the Meta Graph API: register,
list and delete message templates, and subscribe the app to the account's webhooks. They talk
direct Graph REST through tai42-kit's curl client (no vendor SDK); the Graph host and pinned
API version ride the settings below. This page is the per-tool index and the settings.

## Configuration

| Variable | Default | Effect |
| - | - | - |
| `CHANNEL_WHATSAPP_ACCESS_TOKEN` | unset | Graph API bearer token. Missing or empty raises on every tool call. |
| `CHANNEL_WHATSAPP_WABA_ID` | unset | WhatsApp Business Account id the endpoints hang under. Missing or empty raises on every tool call. |
| `CHANNEL_WHATSAPP_API_BASE_URL` | `https://graph.facebook.com/v23.0` | Graph API origin with a pinned version. |
| `CHANNEL_WHATSAPP_HTTP_TIMEOUT_SECONDS` | `30` | Per-request HTTP timeout in seconds. |

The token and WABA id share the `CHANNEL_WHATSAPP_` env group with the rest of the WhatsApp
deployment; the access token is held as a secret and never appears in a log or a raised error.
Every non-2xx from Graph raises loudly with Graph's status and body — never a silent default.

## register\_whatsapp\_template

Registers a message template on the account and returns Graph's response (the template id and
review status). `components` is the Graph-shaped component list, passed through unchanged; `name`,
`language`, `category` and `components` are all required and non-empty.

## list\_whatsapp\_templates

Lists every message template on the account, following Graph's paging cursors to exhaustion, and
returns the concatenated entries.

## delete\_whatsapp\_template

Deletes a message template by name (percent-encoded into the query) and returns Graph's response.

## subscribe\_whatsapp\_app

Subscribes the app to the account's webhooks. With both `callback_uri` and `verify_token` given it
sends Meta's override pair; with neither it subscribes to the app's configured webhook; supplying
exactly one of the two raises.


# webhook-verifier-github
Source: https://docs.tai42.ai/plugins/tai42/webhook-verifier-github

GitHub webhook-signature verifier plugin for the TAI ecosystem: a per-provider WebhookVerifier that checks each delivery's X-Hub-Signature-256 HMAC before the payload is dispatched.

> [!NOTE]
>
> `Webhook verifier` plugin · listing `tai42/webhook-verifier-github`

## Install

```bash theme={null}
tai plugins install tai42-webhook-verifier-github
```

## Permissions

| Capability | Declared |
| - | - |
| Network | no |
| Subprocess | no |
| Filesystem | no |

## Provides

### github

`Webhook verifier` — Verify a GitHub webhook delivery's X-Hub-Signature-256 HMAC before dispatch.

Registers the `github` webhook verifier. It authenticates an inbound delivery's
`X-Hub-Signature-256` HMAC-SHA256, computed over the exact raw request body and keyed
by the webhook's shared secret. Bind it to a hook topic to close that topic's door
against unsigned deliveries.

## Bind it to a topic

A verifier is bound per hook topic. The binding names the environment variable that
holds the signing secret through `config.secret_env` — the verifier looks that
variable up at verify time, so the secret itself never lives in the manifest:

```bash theme={null}
curl -X PUT .../api/hooks/topics/{topic}/verifier \
  -d '{"verifier": "github", "config": {"secret_env": "GITHUB_WEBHOOK_SECRET"}}'
```

Set the same secret you configured on the GitHub webhook in that variable on every
process that receives deliveries:

```bash theme={null}
GITHUB_WEBHOOK_SECRET=...
```

The variable name is yours to choose — pick a distinct name per topic when one
deployment verifies several GitHub webhooks with different secrets.

### Replay window

GitHub sends no signed timestamp, so replay is defended by remembering each delivery's
`X-GitHub-Delivery` id in a seen-set. `config` takes an optional `replay_window_seconds`
(a positive int, default `86400` — one day) setting how long an id is remembered:

```json theme={null}
{"verifier": "github", "config": {"secret_env": "GITHUB_WEBHOOK_SECRET", "replay_window_seconds": 86400}}
```

A delivery whose id was already seen within that window is refused as a replay. A manual
redelivery of the same event carries the same id and is the correct idempotent no-op.

## Behaviour

* **Fails closed.** A missing `secret_env` key, a missing environment variable, an
  empty secret, a missing `X-GitHub-Delivery` header, or a non-positive / non-int
  `replay_window_seconds` raises loudly rather than degrading to an unauthenticated
  door. A malformed or mismatched signature is an ordinary verification failure.
* **Replay-deduped.** Each delivery's `X-GitHub-Delivery` id is remembered in a
  seen-set for `replay_window_seconds` (default one day); a replay within the window is
  refused and nothing re-dispatches.
* **POST only.** The signature covers the raw body, so a door binding this verifier
  rejects GET.
* The comparison is constant-time, and the `sha256=` digest must be exactly 64 hex
  characters.

## See also

* [Triggers and webhooks](/concepts/triggers-and-webhooks) — the verifier model and the built-in `shared_secret` verifier.


# webhook-verifier-stripe
Source: https://docs.tai42.ai/plugins/tai42/webhook-verifier-stripe

Stripe webhook-signature verifier plugin for the TAI ecosystem: a per-provider WebhookVerifier that checks each delivery's Stripe-Signature HMAC before the payload is dispatched.

> [!NOTE]
>
> `Webhook verifier` plugin · listing `tai42/webhook-verifier-stripe`

## Install

```bash theme={null}
tai plugins install tai42-webhook-verifier-stripe
```

## Permissions

| Capability | Declared |
| - | - |
| Network | no |
| Subprocess | no |
| Filesystem | no |

## Provides

### stripe

`Webhook verifier` — Verify a Stripe webhook delivery's Stripe-Signature HMAC before dispatch.

Registers the `stripe` webhook verifier. It authenticates an inbound delivery's
`Stripe-Signature` HMAC-SHA256 over `{timestamp}.{raw body}`, keyed by the endpoint's
signing secret, and enforces a freshness window against replay. It is the verifier
binding behind the platform's Stripe payments flow.

## Bind it to a topic

A verifier is bound per hook topic. The binding names the environment variable that
holds the endpoint's signing secret through `config.secret_env` — the verifier looks
that variable up at verify time, so the secret itself never lives in the manifest:

```bash theme={null}
curl -X PUT .../api/hooks/topics/payments/verifier \
  -d '{"verifier": "stripe", "config": {"secret_env": "STRIPE_WEBHOOK_SECRET"}}'
```

Set the signing secret from the Stripe dashboard webhook endpoint in that variable on
every process that receives deliveries:

```bash theme={null}
STRIPE_WEBHOOK_SECRET=whsec_...
```

The variable name is yours to choose — pick a distinct name per topic when one
deployment verifies several Stripe endpoints with different secrets.

### Replay window

`config` takes an optional `tolerance_seconds` (a positive int, default `300`), the
age past which a delivery is rejected:

```json theme={null}
{"verifier": "stripe", "config": {"secret_env": "STRIPE_WEBHOOK_SECRET", "tolerance_seconds": 300}}
```

Only a stale timestamp is rejected; a future timestamp is not, since sender clock skew
is not an attack signal.

Within that window the verifier also dedupes replays. After a delivery passes, its
Stripe `event.id` (the top-level `evt_…`) is claimed in a seen-set, so a captured signed
delivery replayed inside the window is refused rather than dispatched again.
The seen-set TTL runs until the signed freshness window ends (`t + tolerance_seconds`) —
anchored to the signed timestamp and rounded up so an id is never forgotten before that
window ends. `tolerance_seconds` is the knob that sets the window.

## Behaviour

* **Fails closed.** A missing `secret_env` key, a missing environment variable, an
  empty secret, or a non-positive `tolerance_seconds` raises loudly rather than
  degrading to an unauthenticated door. A malformed or mismatched signature is an
  ordinary verification failure.
* **Rotation-tolerant.** A header may carry several `v1=` digests during a secret
  rotation; any one that matches passes, and a malformed candidate is dropped rather
  than rejecting the delivery.
* **Replay-deduped.** A delivery that passes verification claims its `event.id` in a
  seen-set; a replay within the window is refused and nothing re-dispatches. The
  seen-set TTL runs until the signed freshness window ends (`t + tolerance_seconds`).
* **POST only.** The signature covers the raw body, so a door binding this verifier
  rejects GET.

## See also

* [Triggers and webhooks](/concepts/triggers-and-webhooks) — the verifier model and the built-in `shared_secret` verifier.
* [Use interactions](/guides/use-interactions) — the full Stripe payments deployment this verifier anchors.


# HTTP API
Source: https://docs.tai42.ai/reference/api/index

The operator HTTP surface served under /api/*, with API-key auth and a data/error envelope.

The HTTP API is the operator surface of a running server. Every route lives
under `/api/*`, takes and returns JSON, and authenticates with an API key. The
per-endpoint pages in this section render directly from the server's OpenAPI 3.1
specification, so they never drift from the code.

## Base URL

The API is served by the running server, alongside the MCP endpoint and the
Studio. Prefix every path with the server's address:

```
https://<your-server>/api
```

A local server started with `tai serve` answers at `http://127.0.0.1:8000/api`.

## Authentication

Every request carries an API key in the `x-api-key` header. Mint and manage keys
with `tai keys` or the `/api/auth/api-keys` routes.

```bash theme={null}
curl https://<your-server>/api/tools \
  -H "x-api-key: $TAI_API_KEY"
```

A missing or invalid key returns `401` with the error envelope below.

> [!NOTE]
>
> A key's access-control condition scopes what it may call. See
> [access control](/concepts/access-control) for the policy model.

## Response envelope

Successful responses wrap their payload in a `data` field:

```json theme={null}
{
  "data": { "...": "the endpoint's result" }
}
```

Errors return an `error` field carrying a human-readable message:

```json theme={null}
{
  "error": "missing or invalid api key"
}
```

The two envelopes never mix — a response carries `data` or `error`, never both.

## Expression fields

Some string properties in the schema hold a **jq expression** rather than an
ordinary value. Those properties declare themselves: each carries an
`x-tai42-expression` vendor annotation, so a client recognizes the field as an
expression and learns its input and output without guessing from the field name.

```json theme={null}
"condition": {
  "type": "string",
  "x-tai42-expression": {
    "language": "jq",
    "label": "condition",
    "blurb": "the declaring surface's input document",
    "returns": "truthy to proceed; a falsy result gates the surface's action off"
  }
}
```

`language` is always present and is `jq`. The rest describe the expression's
context and are emitted only when the declaring surface supplies them: `label` is a
short name for what `.` is, `blurb` says what the input document is, `keys` glosses
the input's known top-level keys as `name`/`gloss` pairs, `returns` says what the
result is consumed as, `caveats` lists evaluation edge cases, and `sample` carries a
representative input document.

The annotation is metadata only. An `x-`-prefixed keyword is ignored by JSON Schema
validation, so it can never change which values a schema accepts, and a field
without one generates a byte-identical schema to a plain string declaration. A
client that does not recognize the annotation, or the `language` it declares,
renders the field as a plain string input.

> [!NOTE]
>
> The [Studio SDK's](/reference/studio-sdk/schema-forms) `SchemaForm` acts on this
> annotation directly: an annotated field renders the
> [visual jq editor](/studio/jq-editor) instead of a text box, with no per-field code.

## Error model

| Status | Meaning |
| - | - |
| `400` | The request body or parameters failed validation. |
| `401` | The `x-api-key` header is missing or invalid. |
| `404` | The addressed resource does not exist. |
| `500` | An unexpected server error — the body carries a correlation `error_id`. |
| `503` | The server is applying a config reload — retry shortly. |

## The reload-gated 503

When the server applies a configuration reload, routes that mutate state — and every
door that would start a conversation turn, a channel's inbound webhook included — return
`503` until the reload completes. The body sets `reloading` to `true` and the
response carries a `Retry-After` header with the seconds to wait:

```json theme={null}
{
  "error": "reloading — the server is applying a config reload; retry shortly",
  "reloading": true
}
```

Retry the request after the `Retry-After` interval. Read-only routes stay
available throughout a reload.

## Unexpected errors and validation

Every error is JSON with an `error` field and nothing beyond it that could leak.
An unexpected, unhandled server error answers a uniform `500` on every serving
path — the body is a fixed envelope carrying a correlation id and no internal
detail:

```json theme={null}
{
  "error": "Internal Server Error",
  "error_id": "3f9c2a1e8b7d4f60a1c2e3d4f5a6b7c8"
}
```

The `error_id` correlates the response to the server-log line that records the
full traceback under the same id; the internal exception text — hosts, file paths,
stack frames — never reaches the client. Quote the `error_id` when reporting a
fault.

On the generic operation body-validation path (the adapter's `422`) and the
connectors mutation doors, a validation failure names **which** fields failed and
**how**, never **what** you sent: the body lists each offending field's path and
its error type only, with the rejected input values stripped, so a secret
submitted in a rejected field there does not ride back out.

Seventeen doors take their operation's plain request model and are parsed by the shared operation
adapter: `POST /api/auth/principals`, `PUT /api/auth/principals/{user_id}`, `POST /api/auth/roles`,
`PUT /api/auth/roles/{name}`, `POST /api/auth/roles/{name}/rollback`,
`POST /api/auth/roles/{name}/grants`, `POST /api/auth/member-actions/invoke`, `POST /api/login/claim`,
`POST /api/config/reload`, `POST /api/marketplace/install`, `POST /api/marketplace/install/preview`,
`POST /api/marketplace/uninstall`, `POST /api/marketplace/update`, `POST /api/notifications`,
`POST /api/resources/get`, `POST /api/tools/reload` and `POST /api/tools/remove`. On these a body that
does not parse answers `400 malformed request body`, and a non-object body or a model break answers
`422` with the field list above. Every other door of the platform's own that takes a JSON body
reads it itself — the interaction answer, reaction and callback doors included — and answers one set of `400` texts:
`invalid JSON body` for a body that does not parse (a deeply nested one included), `body must be a
JSON object` for one that is not an object, and `invalid <what>: <field>: <rule>; …` for a body that
breaks its model — each declared field path beside the message pydantic gives for the bound it
violates (`invalid hook params: topic: String should have at least 1 character`). A door then names
a missing required field in its own words (`body must contain 'answer'`). Four of them answer a
model break with a fixed text instead: the three connector mutation doors (connect, reconnect,
sub-services) answer `400 invalid request body` with the failing fields' paths and types under
`fields`, and the setup door answers `422 invalid request body`. The public webhook ingress
doors (`/universal_webhook/{topic}`, `/trigger/{token}`) are not among them: they accept any JSON
value and refuse a malformed one in their own ingest envelope, `{"status": "rejected", "error": "malformed JSON body: …"}` (the
topic door's envelope also carries its `topic`). A plugin's doors (a channel's, an accounts
provider's) answer the texts the plugin documents. A model's own named rule (a hook topic or a sub-MCP slug that is not one lowercase path
segment) quotes the value it refuses, so do not rely on every error response to withhold
rejected input.

## The published specification

The `tai42-skeleton` package ships its OpenAPI specification as a committed file,
`tai42_skeleton/schemas/openapi.json`, so a client can generate its types from the
exact version it installs. The file covers the platform's core routes; each plugin
publishes its own routes. Regenerate it after a route or response-model change with:

```bash theme={null}
tai openapi --out core/skeleton/src/tai42_skeleton/schemas/openapi.json
```

The skeleton's tests fail when the committed file no longer matches a fresh build,
naming each path and component that drifted. Its `info.version` is the package
version, written by the release tooling with every release, so a version-only
difference is reported on its own line.

Two details a client generator reads:

* Every response field with a closed set of values publishes them as an `enum` (a
  route's methods, a plugin's delivery, a thread's control mode, a run's status, …),
  so a generated client refuses a value outside the set.
* A path parameter that matches across `/` separators carries
  `"x-tai42-converter": "path"`; the path template itself drops the converter.

The contract package publishes the companion JSON-schema bundle,
`tai42_contract/schemas/contract-schema.json` (regenerated with
`tai42-contract-schemas --out`): the served documents, the conformance vectors, and
the served `constants` a client reads instead of re-spelling (`PERSON_KIND`,
`MEDIA_ROUTE_PREFIX`, `MEDIA_ID_PATTERN`).

> [!TIP]
>
> Regenerate this reference from the running code with `tai openapi --out
>     openapi.json` — the same offline emitter the docs pipeline runs.


# Capability map
Source: https://docs.tai42.ai/reference/capability-map

A code-anchored index of every platform capability — HTTP API operations, listed plugins, settings groups, and agents & extensions — each linked to its docs page and its source in the public monorepo.

Every capability the platform exposes, one row apiece, linked to its documentation and its source. Feature areas are fixed; rows are derived from machine-readable sources (the generated OpenAPI, the plugin registry, the settings registry, and the agent/extension registrations), never authored by hand.

## HTTP API

### Access Control

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `DELETE /api/auth/api-keys/&#123;user_id&#125;` | Revoke an api key | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/auth/principals/&#123;user_id&#125;` | Delete a principal | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/auth/public-routes` | Unpin a public route | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/auth/roles/&#123;name&#125;` | Delete a role | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/auth/scopes/urls` | Remove a URL from all scopes | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/auth/scopes/&#123;scope_id&#125;` | Delete a scope | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/auth/api-keys/&#123;user_id&#125;/policy/versions` | List a user's policy version history | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/auth/capabilities` | Report key-mint capabilities | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/auth/me` | The caller's capability projection | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/auth/member-actions` | List member actions | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/auth/members` | List members and invites | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/auth/principals` | List principals | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/auth/public-routes` | List public-pinned routes | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/auth/roles` | List roles | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/auth/roles/&#123;name&#125;/versions` | A role's version history + audit trail | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/auth/routes` | List the app's HTTP routes and their scope mappings | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/auth/scopes` | List all scopes | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/auth/tokens-payload` | List api-key token payloads | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/auth/api-keys` | Create an api key | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/auth/api-keys/&#123;user_id&#125;/policy/rollback` | Roll a policy back to a version | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/auth/api-keys/&#123;user_id&#125;/scopes` | Add/remove scopes on an api key | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/auth/claim-links` | Create a one-time claim link for an API key | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/auth/logout` | Log out the current session | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/auth/member-actions/invoke` | Invoke a member action | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/auth/principals` | Create a principal | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/auth/public-routes` | Pin a route public | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/auth/roles` | Create a role | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/auth/roles/&#123;name&#125;/grants` | Set/remove single tag grants on a role | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/auth/roles/&#123;name&#125;/rollback` | Roll a role back to a version | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/auth/scopes` | Add a URL to a scope | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/auth/validate-condition` | Validate a jq policy condition | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/setup` | Initialize the deployment (owner + first key) | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PUT /api/auth/api-keys/&#123;user_id&#125;` | Edit an api key | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PUT /api/auth/principals/&#123;user_id&#125;` | Update a principal | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PUT /api/auth/roles/&#123;name&#125;` | Edit a role's grant map | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Agents

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/agents` | List every registered agent | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/agents/spec-runnable` | List the spec-runnable (authorable) agents | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/agents/authored/&#123;name&#125;/runs` | Stream a run of an authored agent | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/agents/&#123;name&#125;/runs` | Stream a run of an agent | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Backend

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/backend` | Get the backend identity | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/fleet/workers` | List the worker fleet | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/fleet/reload-config` | Soft-restart the worker fleet | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Backup

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/backup/sections` | List backup sections | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/backup/export` | Export the named backup sections | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/backup/import` | Import a backup document | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Channels

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/channels` | List registered channels | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Checkpoints

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `POST /api/checkpoints/sweep` | Sweep expired checkpoint threads | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Config

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `DELETE /api/config/profiles/&#123;name&#125;` | Delete a settings profile | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/config/env` | Read the stored env config and secret-key marks | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/config/mode` | Read the active config backend mode | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/config/profiles` | List settings profiles | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/config/profiles/&#123;name&#125;` | Get a settings profile | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/config/profiles/&#123;name&#125;/versions` | List a settings profile's versions | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/config/profiles/&#123;name&#125;/versions/&#123;version&#125;` | Get a settings profile version | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/config/settings-schema` | List settings groups with their resolved field values | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/config/env` | Merge env overrides and reload the fleet | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/config/profiles/&#123;name&#125;/apply` | Apply a settings profile — replace the stored env and reload the fleet | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/config/profiles/&#123;name&#125;/diff` | Diff a settings profile against the stored env | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/config/profiles/&#123;name&#125;/rollback` | Roll a settings profile back to a version | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/config/reload` | Soft-restart the process from its manifest | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PUT /api/config/profiles/&#123;name&#125;` | Create or update a settings profile | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Connectors

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `DELETE /api/connectors/connections/&#123;connection_id&#125;` | Disconnect a connection | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/connectors/providers/&#123;provider_id&#125;` | Remove a connector provider added by its address | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/connectors/connections` | List connections | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/connectors/connections/&#123;connection_id&#125;` | Get a connection | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/connectors/providers` | List connector providers | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PATCH /api/connectors/connections/&#123;connection_id&#125;/sub-services` | Patch a connection's enabled sub-services | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/connectors/connections/start` | Start a connection flow | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/connectors/connections/&#123;connection_id&#125;/reconnect` | Start a reconnect flow | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/connectors/oauth/complete` | Complete an OAuth connection flow | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/connectors/providers` | Add an MCP server as a connector provider | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/connectors/providers/discover` | Look up an MCP server's sign-in | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/connectors/tokens/reencrypt` | Re-encrypt connector tokens and client credentials under the current KEK | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PUT /api/connectors/providers/&#123;provider_id&#125;/client` | Set the client credentials of a connector provider | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Conversations

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `DELETE /api/conversation-configs/&#123;target_kind&#125;/&#123;target_name&#125;` | Delete a conversation target config | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/conversations/persons/&#123;person_id&#125;` | Delete a conversation person | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/conversations/&#123;route_name&#125;` | Delete a conversation route | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/conversations/&#123;route_name&#125;/thread` | Delete a conversation thread | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/conversation-configs` | List conversation target configs | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/conversation-configs/&#123;target_kind&#125;/&#123;target_name&#125;` | Get a conversation target config | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/conversations` | List conversation routes | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/conversations/messages/failed` | List failed conversation deliveries | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/conversations/persons/&#123;person_id&#125;` | Read a conversation person | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/conversations/&#123;route_name&#125;` | Get a conversation route | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/conversations/&#123;route_name&#125;/messages/search` | Search a conversation route's messages | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/conversations/&#123;route_name&#125;/messages/&#123;message_id&#125;` | Read one conversation answer record | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/conversations/&#123;route_name&#125;/thread/mode` | Read a conversation thread's control mode | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/conversations/&#123;route_name&#125;/threads` | List a conversation route's threads | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/conversations/&#123;route_name&#125;/transcript` | Read a conversation thread's transcript | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/conversations/&#123;route_name&#125;` | Create or replace a conversation route | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/conversations/&#123;route_name&#125;/events` | Deliver a structured event to a conversation thread as a turn | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/conversations/&#123;route_name&#125;/messages` | Send a message to a conversation route | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/conversations/&#123;route_name&#125;/thread/messages` | Send an operator message into a conversation thread | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PUT /api/conversation-configs/&#123;target_kind&#125;/&#123;target_name&#125;` | Create or replace a conversation target config | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PUT /api/conversations/persons/&#123;person_id&#125;/locale` | Set a conversation person's locale | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PUT /api/conversations/&#123;route_name&#125;/thread/mode` | Set a conversation thread's control mode | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Extensions

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/extensions` | List every registered extension | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/tools/&#123;name&#125;/extensions` | Get a tool's applied extension combos | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/tools/&#123;name&#125;/extensions` | Set a tool's applied extension combos | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/tools/&#123;name&#125;/extensions/combos` | Add or remove single extension combos on a tool | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Hooks

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `DELETE /api/hook-runs/&#123;id&#125;` | Discard a failed hook run | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/hooks/topics/&#123;topic&#125;/verifier` | Unbind a topic's webhook verifier | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/hooks/trigger-links/&#123;name&#125;` | Delete a trigger link | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/hooks/&#123;name&#125;` | Unregister a hook | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/hook-runs` | List hook runs | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/hooks` | List registered hooks | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/hooks/trigger-links` | List trigger links | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/hooks/verifiers` | List registered webhook verifiers | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/hook-runs/&#123;id&#125;/retry` | Retry a failed hook run | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/hooks` | Register a hook | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/hooks/trigger-links` | Create a trigger link | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PUT /api/hooks/topics/&#123;topic&#125;/verifier` | Bind a webhook verifier to a topic | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Interactions

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/interactions` | List pending interactions | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/interactions/callback/&#123;ticket&#125;` | External interaction callback door | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/interactions/media/&#123;media_id&#125;` | Serve interaction media stored by reference | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/interactions/pending` | List parked (async) interactions awaiting an answer | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/interactions/stream` | Stream the interactions inbox live tail | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/interactions/callback/&#123;ticket&#125;` | External interaction callback door | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/interactions/callback/&#123;ticket&#125;/react` | External interaction mid-form reaction door | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/interactions/&#123;interaction_id&#125;/answer` | Answer a pending interaction | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/interactions/&#123;interaction_id&#125;/cancel` | Cancel a pending interaction | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/interactions/&#123;interaction_id&#125;/react` | React to an open form interaction | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Login

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/login/methods` | List available login methods | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/login/claim` | Exchange a one-time claim token for its API key | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Manifest

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `DELETE /api/agents-config/entries/&#123;title&#125;` | Remove one agents config entry by title and hot-reload | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/mcp-config/entries/&#123;title&#125;` | Remove one MCP config entry by title and hot-reload | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/tools-config/entries/&#123;title&#125;` | Remove one tools config entry by title and hot-reload | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/manifest` | Read the PRESERVED manifest MCP section and user tools | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/manifest/mcp-env-refs` | List the manifest MCP section's !ENV marker refs (names + set/unset only) | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/manifest/preserved` | Read the PRESERVED manifest (markers intact) MCP section and user tools | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/mcp-config/schema` | Get the JSON schema for one MCP-config entry | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/mcp-status` | Snapshot the live MCP binding status | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/mcp-status/failed` | List MCP servers skipped by the viability check | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/agents-config/entries` | Add or replace agents config entries and hot-reload | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/api-tools` | Add/remove names on the api\_tools include/exclude lists and hot-reload | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/manifest/replace` | Replace the whole manifest, persist, and reload the fleet | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/mcp-config` | Replace the MCP config section and hot-reload | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/mcp-config/entries` | Add or replace MCP config entries and hot-reload | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/mcp-config/secret-env` | Write a secret env value and its manifest !ENV marker together, then reload | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/mcp-status/reload-failed` | Re-probe every failed MCP server | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/mcp-status/&#123;title&#125;/deregister` | Detach a single MCP server's tools by title | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/mcp-status/&#123;title&#125;/reload` | Reload a single MCP server by title | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/tools-config/entries` | Add or replace tools config entries and hot-reload | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Marketplace

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/marketplace/advisories` | Get advisories for installed plugins | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/marketplace/categories` | List marketplace categories | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/marketplace/installed` | List installed marketplace plugins | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/marketplace/kinds` | List marketplace item kinds | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/marketplace/plugins/&#123;ns&#125;/&#123;name&#125;` | Get a marketplace listing's detail | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/marketplace/search` | Search the marketplace | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/marketplace/install` | Install a marketplace plugin | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/marketplace/install/preview` | Preview a marketplace install | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/marketplace/uninstall` | Uninstall a marketplace plugin | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/marketplace/update` | Update a marketplace plugin | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/marketplace/upgrade-all` | Upgrade all installed marketplace plugins | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Notifications

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/notifications` | List internal notifications | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/notifications` | Send a human a one-way notification | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Observability

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/observability/capabilities` | Get the monitoring backend's observability capabilities | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/observability/metrics` | Query observability metrics | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/observability/runs` | List observability runs | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/observability/runs/export` | Export runs as a CSV download | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/observability/runs/&#123;trace_id&#125;/spans/&#123;span_id&#125;/resolved` | Get a run span's resolved value | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/observability/runs/&#123;trace_id&#125;/trace` | Get a run's trace | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/observability/runs/&#123;trace_id&#125;/trace/export` | Export a run's trace as a JSON download | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/observability/runs/&#123;trace_id&#125;/trace/outline` | Get a run's trace outline | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Plugins

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/plugins` | List the registered studio plugins | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/plugins/&#123;name&#125;/studio/&#123;path&#125;` | Serve a studio plugin asset | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Presets

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `DELETE /api/presets/&#123;name&#125;` | Delete a preset | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/presets` | List presets | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/presets/&#123;name&#125;` | Get a preset | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/presets/&#123;name&#125;/referees` | List live references to this preset | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/presets/&#123;name&#125;/versions` | List a preset's versions | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/presets/&#123;name&#125;/versions/&#123;version&#125;` | Get a specific preset version | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/presets` | Create a preset | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/presets/validate` | Validate a preset draft (dry-run) | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/presets/&#123;name&#125;/rename` | Rename a preset | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/presets/&#123;name&#125;/rollback` | Roll a preset back to a version | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/presets/&#123;name&#125;/versions` | Save a new preset version | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PUT /api/presets/&#123;name&#125;/versions/&#123;version&#125;/tags` | Set a preset version's tags | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Resources

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/resources/get` | Load a stored resource by id, optionally rendering it | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/resources/get` | Load a stored resource by id, optionally rendering it | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Runs

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/runs` | List platform runs | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/runs/prune` | Prune the platform runs index | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Sandbox

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/sandbox` | Get the sandbox identity and resolved policy | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Schedules

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `DELETE /api/schedules/&#123;schedule_name&#125;` | Delete a schedule | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/schedules` | List schedules | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/schedules/server-datetime` | Get the server date and time | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/schedules` | Create a schedule | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### States

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `DELETE /api/state-pending-saves/&#123;id&#125;` | Discard a failed pending state save | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/state-templates/&#123;name&#125;` | Delete a state template | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/states/&#123;name&#125;` | Delete a state | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/states/&#123;name&#125;/attachments/&#123;template&#125;` | Detach a template from a state | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/states/&#123;name&#125;/records/&#123;target_kind&#125;/&#123;target_name&#125;/&#123;kind&#125;/&#123;key&#125;` | Erase a subject's record | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/state-pending-saves` | List pending state saves | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/state-templates` | List state templates | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/state-templates/&#123;name&#125;` | Get a state template | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/states` | List declared states | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/states/&#123;name&#125;` | Get a state | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/states/&#123;name&#125;/attachments` | List a state's attachments | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/states/&#123;name&#125;/attachments/&#123;template&#125;` | Get a state's attachment | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/states/&#123;name&#125;/consumers` | A state's consumers | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/states/&#123;name&#125;/records/check` | Check a state's stored records against its schema | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/states/&#123;name&#125;/records/&#123;target_kind&#125;/&#123;target_name&#125;/&#123;kind&#125;/&#123;key&#125;` | Read a subject's record | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/states/&#123;name&#125;/records/&#123;target_kind&#125;/&#123;target_name&#125;/&#123;kind&#125;/&#123;key&#125;/template-jq/&#123;program&#125;` | Evaluate an input-purpose template\_jq program for a subject | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/states/&#123;name&#125;/records/&#123;target_kind&#125;/&#123;target_name&#125;/&#123;kind&#125;/&#123;key&#125;/writes` | A subject's write audit trail | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/states/&#123;name&#125;/stats` | A state's record statistics | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/states/&#123;name&#125;/subjects` | List a state's subjects | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PATCH /api/states/&#123;name&#125;/attachments/&#123;template&#125;` | Update an attachment's declarations | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PATCH /api/states/&#123;name&#125;/records/&#123;target_kind&#125;/&#123;target_name&#125;/&#123;kind&#125;/&#123;key&#125;` | Merge into a subject's record | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/state-pending-saves/&#123;id&#125;/retry` | Retry a failed pending state save | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/state-retention/prune` | Prune expired state records | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/states/&#123;name&#125;/records/search` | Search a state's records | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/states/&#123;name&#125;/records/validate` | Validate a candidate record against a state's schema | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/states/&#123;name&#125;/records/&#123;target_kind&#125;/&#123;target_name&#125;/&#123;kind&#125;/&#123;key&#125;/deltas` | Apply ops to a subject's record | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/states/&#123;name&#125;/records/&#123;target_kind&#125;/&#123;target_name&#125;/&#123;kind&#125;/&#123;key&#125;/fold` | Fold one subject into another | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/states/&#123;name&#125;/records/&#123;target_kind&#125;/&#123;target_name&#125;/&#123;kind&#125;/&#123;key&#125;/template-jq/&#123;program&#125;` | Apply an update-purpose template\_jq program to a subject's record | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PUT /api/state-templates/&#123;name&#125;` | Create or replace a state template | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PUT /api/states/&#123;name&#125;` | Create or re-declare a state | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PUT /api/states/&#123;name&#125;/attachments/&#123;template&#125;` | Attach a template on a state | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PUT /api/states/&#123;name&#125;/records/&#123;target_kind&#125;/&#123;target_name&#125;/&#123;kind&#125;/&#123;key&#125;` | Replace a subject's record | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Storage

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `DELETE /api/storage/dirs/&#123;dir_path&#125;` | Delete a storage directory | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/storage/resources/&#123;resource_id&#125;` | Delete a storage resource | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/storage` | Get the storage provider identity | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/storage/resources` | List storage resources | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/storage/resources/&#123;resource_id&#125;/content` | Download a storage resource | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/storage/resources/&#123;resource_id&#125;/stat` | Stat a storage resource | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/storage/resources` | Upload a storage resource | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Sub Mcp

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `DELETE /api/sub-mcp/&#123;slug&#125;` | Unregister a sub-MCP app | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/sub-mcp` | List the registered sub-MCP apps | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/sub-mcp` | Register or reload a sub-MCP app | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### System

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/system/kinds` | List pluggable-kind status | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Templates

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/templates` | List templates | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/clear-templates-cache` | Clear the template render cache | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/delete-template` | Delete a template | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/delete-template-dir` | Delete a template directory | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/render-template` | Render a template | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/template` | Fetch a template and its schema | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/upload-template` | Upload a template | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Tool Runs

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/tool-runs` | List background tool runs for a tool | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/tool-runs/&#123;run_id&#125;` | Get a background tool run's status and result | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/tool-runs` | Submit a tool for background execution | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Tool Meta

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `DELETE /api/tool-meta/folders/&#123;folder_id&#125;` | Delete a folder | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `DELETE /api/tool-meta/tools/&#123;tool_name&#125;` | Delete a tool's overlay row | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/tool-meta` | List the tool-metadata overlay | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `PATCH /api/tool-meta/tools/&#123;tool_name&#125;` | Upsert a tool's overlay | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/tool-meta/folders` | Create a folder | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/tool-meta/folders/&#123;folder_id&#125;/move` | Move a folder | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/tool-meta/folders/&#123;folder_id&#125;/rename` | Rename a folder | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

### Tools

| Operation | What it does | Docs | Source |
| - | - | - | - |
| `GET /api/tools` | List the registered tool names | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/tools-schema` | Get the input/output schema of every tool | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/tools/tags` | List each tool's native tags, declared visibility, and badges | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `GET /api/tools/&#123;tool_name&#125;/schema` | Get one tool's input/output schema | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/run-tool` | Run a registered tool synchronously | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/tools/reload` | Reload one app tool from its stored definition | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |
| `POST /api/tools/remove` | Remove one app tool from the live registry | [API](/reference/api) | [operations](https://github.com/tai42ai/tai42/tree/main/core/skeleton/src/tai42_skeleton/operations) |

## Plugins

| Item | What it provides | Docs | Source |
| - | - | - | - |
| `accounts-postgres` | Postgres-backed accounts/identity provider — owns user accounts, password login, sessions, and invites. | [accounts-postgres](/plugins/tai42/accounts-postgres) | `tai42_accounts_postgres.provider` |
| `login` | The public /api/login/\* routes. | [accounts-postgres](/plugins/tai42/accounts-postgres) | `tai42_accounts_postgres.routes_login` |
| `users` | The authed /api/auth/users/me/password self-service password route. | [accounts-postgres](/plugins/tai42/accounts-postgres) | `tai42_accounts_postgres.routes_users` |
| `langchain_deep_agent` | Run a deep agent with planning, subagents, skills, and a filesystem backend. | [agents](/plugins/tai42/agents) | `tai42_agents.langchain_deep_agent` |
| `claude_code` | Run Claude Code inside a sandbox: it drives the real claude binary over a versioned exec protocol, with tools, skills, and subagents. | [agents](/plugins/tai42/agents) | `tai42_agents.claude_code` |
| `refine_agent` | Run an Evaluator-Critic refinement loop until the Critic approves or the budget runs out. | [agents](/plugins/tai42/agents) | `tai42_agents.refine_agent` |
| `voting_agent` | Run a voting workflow — voter LLMs answer in parallel, then a judge LLM decides. | [agents](/plugins/tai42/agents) | `tai42_agents.voting_agent` |
| `retrieval_tools_agent` | A tools agent that retrieves its tools on demand from a vector store. | [agents](/plugins/tai42/agents) | `tai42_agents.retrieval_tools_agent` |
| `tools_agent` | Run a LangGraph tools agent over tools loaded by name (and optional presets). | [agents](/plugins/tai42/agents) | `tai42_agents.tools_agent` |
| `vqa_agent` | Analyze an image and answer a query about it using a multimodal LLM. | [agents](/plugins/tai42/agents) | `tai42_agents.vqa_agent` |
| `arq` | arq execution backend — background tool runs and schedules over Redis. | [backend-arq](/plugins/tai42/backend-arq) | `tai42_backend_arq.backend` |
| `celery` | Celery execution backend — worker/beat/flower runtime, prefork-pool turnover on worker-bus ops, and RedBeat scheduling. | [backend-celery](/plugins/tai42/backend-celery) | `tai42_backend_celery.core.backend` |
| `rq` | RQ execution backend — background tool runs and schedules over Redis. | [backend-rq](/plugins/tai42/backend-rq) | `tai42_backend_rq.backend` |
| `slack` | Deliver ask questions to a Slack channel and bridge the threaded reply back. | [channel-slack](/plugins/tai42/channel-slack) | `tai42_channel_slack.register` |
| `telegram` | Deliver ask questions to a Telegram chat and bridge the typed reply back. | [channel-telegram](/plugins/tai42/channel-telegram) | `tai42_channel_telegram.register` |
| `twilio` | Deliver ask questions to a phone over Twilio SMS/WhatsApp and bridge the reply back. | [channel-twilio](/plugins/tai42/channel-twilio) | `tai42_channel_twilio.register` |
| `web` | Deliver ask questions to a visitor in the public chat page and bridge the reply back. | [channel-web](/plugins/tai42/channel-web) | `tai42_channel_web.register` |
| `web` | The entry-gate and words panels on a web route's drill-in. | [channel-web](/plugins/tai42/channel-web) | `tai42_channel_web` |
| `whatsapp` | Deliver ask questions to a human on WhatsApp via the Meta Cloud API and bridge the reply back. | [channel-whatsapp](/plugins/tai42/channel-whatsapp) | `tai42_channel_whatsapp.register` |
| `atlassian` | OAuth connector for Atlassian (Jira, Confluence, Compass). | [connector-atlassian](/plugins/tai42/connector-atlassian) | — |
| `github` | OAuth connector for GitHub over GitHub's hosted MCP server. | [connector-github](/plugins/tai42/connector-github) | — |
| `google` | OAuth connector for Google Workspace on Google's hosted MCP servers. | [connector-google](/plugins/tai42/connector-google) | — |
| `slack` | OAuth connector for Slack over Slack's hosted MCP server. | [connector-slack](/plugins/tai42/connector-slack) | — |
| `redis` | Redis-backed api-key identity provider — validate inbound tokens and provision keys. | [identity-redis](/plugins/tai42/identity-redis) | `tai42_identity_redis.redis_api_key_provider` |
| `mcp-dynamic-postgres` | Schema-driven generator for safe, scoped PostgreSQL DML tools in FastMCP agent systems | [mcp-dynamic-postgres](/plugins/tai42/mcp-dynamic-postgres) | — |
| `langfuse` | Langfuse monitoring backend — trace/span emission and the observability read surface. | [monitoring-langfuse](/plugins/tai42/monitoring-langfuse) | `tai42_monitoring_langfuse.register` |
| `docker` | Docker sandbox provider — per-session containers on a remote engine over the Docker Engine API. | [sandbox-docker](/plugins/tai42/sandbox-docker) | `tai42_sandbox_docker.provider` |
| `local` | Direct/host sandbox — runs the session's code as a host subprocess, no isolation. | [sandbox-local](/plugins/tai42/sandbox-local) | `tai42_sandbox_local.provider` |
| `github` | Storage backend serving text and binary/media content over a GitHub repository. | [storage-github](/plugins/tai42/storage-github) | `tai42_storage_github` |
| `local` | Storage backend serving text and binary content from a local directory tree. | [storage-local](/plugins/tai42/storage-local) | `tai42_storage_local` |
| `s3` | Storage backend serving text, binary, and media content over an S3 bucket. | [storage-s3](/plugins/tai42/storage-s3) | `tai42_storage_s3` |
| `classify` | Judge JSON state against typed questions and return typed answers. | [toolbox](/plugins/tai42/toolbox) | `tai42_toolbox.tools.classify` |
| `current_time_info` | Return the current time as a structured object. | [toolbox](/plugins/tai42/toolbox) | `tai42_toolbox.tools.current_time_info` |
| `generate_embeddings` | Generate embeddings for a single string or a list of strings. | [toolbox](/plugins/tai42/toolbox) | `tai42_toolbox.tools.generate_embeddings` |
| `generate_uuid` | Generate a random UUID (version 4). | [toolbox](/plugins/tai42/toolbox) | `tai42_toolbox.tools.generate_uuid` |
| `pad_embeddings` | Pad each embedding vector with zeros up to a target dimension. | [toolbox](/plugins/tai42/toolbox) | `tai42_toolbox.tools.pad_embeddings` |
| `request` | Execute an HTTP request through a curl-backed session. | [toolbox](/plugins/tai42/toolbox) | `tai42_toolbox.tools.request` |
| `batch` | Branch a tool into a variant that runs many instances at once. | [toolbox](/plugins/tai42/toolbox) | `tai42_toolbox.extensions.batch` |
| `cache` | Branch a tool into a variant that memoizes results by call arguments. | [toolbox](/plugins/tai42/toolbox) | `tai42_toolbox.extensions.cache` |
| `chain` | Branch a tool into a variant that transforms its output and calls a next tool. | [toolbox](/plugins/tai42/toolbox) | `tai42_toolbox.extensions.chain` |
| `output_schema` | Branch a tool into a variant that forces a configured JSON Schema as its output schema and validates every result against it. | [toolbox](/plugins/tai42/toolbox) | `tai42_toolbox.extensions.output_schema` |
| `prometheus_metrics` | Branch a tool into a variant that records a Prometheus call metric. | [toolbox](/plugins/tai42/toolbox) | `tai42_toolbox.extensions.prometheus` |
| `proxy` | Branch a tool into a variant that runs the wrapped tool through a proxy. | [toolbox](/plugins/tai42/toolbox) | `tai42_toolbox.extensions.proxy` |
| `create_github_webhook` | Create a repository webhook and return its id, url, events, and active flag. | [tools-github](/plugins/tai42/tools-github) | `tai42_tools_github.tools.create_github_webhook` |
| `list_github_webhooks` | List a repository's webhooks, following Link-header pagination to exhaustion. | [tools-github](/plugins/tai42/tools-github) | `tai42_tools_github.tools.list_github_webhooks` |
| `delete_github_webhook` | Delete a repository webhook by id. | [tools-github](/plugins/tai42/tools-github) | `tai42_tools_github.tools.delete_github_webhook` |
| `confirm_stripe_payment` | Answer a paid checkout ask from a Stripe webhook event. | [tools-stripe](/plugins/tai42/tools-stripe) | `tai42_tools_stripe.tools.confirm_stripe_payment` |
| `create_stripe_checkout` | Create a Stripe Checkout Session and return its hosted payment URL. | [tools-stripe](/plugins/tai42/tools-stripe) | `tai42_tools_stripe.tools.create_stripe_checkout` |
| `create_stripe_payment_link` | Create a flexible-amount non-blocking Stripe payment link and return its URL and session id. | [tools-stripe](/plugins/tai42/tools-stripe) | `tai42_tools_stripe.tools.create_stripe_payment_link` |
| `create_stripe_webhook_endpoint` | Create a Stripe webhook endpoint and return its id and one-time signing secret. | [tools-stripe](/plugins/tai42/tools-stripe) | `tai42_tools_stripe.tools.create_stripe_webhook_endpoint` |
| `delete_stripe_webhook_endpoint` | Delete a Stripe webhook endpoint by id. | [tools-stripe](/plugins/tai42/tools-stripe) | `tai42_tools_stripe.tools.delete_stripe_webhook_endpoint` |
| `expire_stripe_checkout` | Expire an open Stripe Checkout Session early and return its id and status. | [tools-stripe](/plugins/tai42/tools-stripe) | `tai42_tools_stripe.tools.expire_stripe_checkout` |
| `list_stripe_webhook_endpoints` | List the account's Stripe webhook endpoints (no signing secrets). | [tools-stripe](/plugins/tai42/tools-stripe) | `tai42_tools_stripe.tools.list_stripe_webhook_endpoints` |
| `reconcile_stripe_payments` | Re-answer paid Stripe checkout sessions the webhook path may have lost. | [tools-stripe](/plugins/tai42/tools-stripe) | `tai42_tools_stripe.tools.reconcile_stripe_payments` |
| `list_twilio_numbers` | List a Twilio account's incoming phone numbers with their inbound-message webhook. | [tools-twilio](/plugins/tai42/tools-twilio) | `tai42_tools_twilio.tools.list_twilio_numbers` |
| `get_twilio_number_webhook` | Read one Twilio number's inbound-message webhook URL and method. | [tools-twilio](/plugins/tai42/tools-twilio) | `tai42_tools_twilio.tools.get_twilio_number_webhook` |
| `set_twilio_number_webhook` | Set a Twilio number's inbound-message webhook to a given https URL. | [tools-twilio](/plugins/tai42/tools-twilio) | `tai42_tools_twilio.tools.set_twilio_number_webhook` |
| `register_whatsapp_template` | Register a WhatsApp message template on the business account and return Graph's id and status. | [tools-whatsapp](/plugins/tai42/tools-whatsapp) | `tai42_tools_whatsapp.tools.register_whatsapp_template` |
| `list_whatsapp_templates` | List every WhatsApp message template on the business account, following Graph's paging to exhaustion. | [tools-whatsapp](/plugins/tai42/tools-whatsapp) | `tai42_tools_whatsapp.tools.list_whatsapp_templates` |
| `delete_whatsapp_template` | Delete a WhatsApp message template by name and return Graph's response. | [tools-whatsapp](/plugins/tai42/tools-whatsapp) | `tai42_tools_whatsapp.tools.delete_whatsapp_template` |
| `subscribe_whatsapp_app` | Subscribe the app to the business account's webhooks, optionally overriding the callback URI and verify token, and return Graph's response. | [tools-whatsapp](/plugins/tai42/tools-whatsapp) | `tai42_tools_whatsapp.tools.subscribe_whatsapp_app` |
| `github` | Verify a GitHub webhook delivery's X-Hub-Signature-256 HMAC before dispatch. | [webhook-verifier-github](/plugins/tai42/webhook-verifier-github) | `tai42_webhook_verifier_github` |
| `stripe` | Verify a Stripe webhook delivery's Stripe-Signature HMAC before dispatch. | [webhook-verifier-stripe](/plugins/tai42/webhook-verifier-stripe) | `tai42_webhook_verifier_stripe` |

## Settings

| Group | What it configures | Docs | Source |
| - | - | - | - |
| `AccessControlRedisSettings` | Access Control Redis Settings (tai42\_skeleton.access\_control.settings) | [Settings](/reference/settings#accesscontrolredissettings) | [`tai42_skeleton.access_control.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `AccessControlSettings` | Access Control Settings (tai42\_skeleton.access\_control.settings) | [Settings](/reference/settings#accesscontrolsettings) | [`tai42_skeleton.access_control.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `AppArgsSettings` | App Args Settings (tai42\_skeleton.settings.settings) | [Settings](/reference/settings#appargssettings) | [`tai42_skeleton.settings.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `AuditLogSettings` | Audit Log Settings (tai42\_skeleton.settings.audit\_log) | [Settings](/reference/settings#auditlogsettings) | [`tai42_skeleton.settings.audit_log`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `BodyLimitSettings` | Body Limit Settings (tai42\_skeleton.settings.body\_limit) | [Settings](/reference/settings#bodylimitsettings) | [`tai42_skeleton.settings.body_limit`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `BusRedisSettings` | Bus Redis Settings (tai42\_skeleton.app.bus\_settings) | [Settings](/reference/settings#busredissettings) | [`tai42_skeleton.app.bus_settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `BusSettings` | Bus Settings (tai42\_skeleton.app.bus\_settings) | [Settings](/reference/settings#bussettings) | [`tai42_skeleton.app.bus_settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `ChannelsSettings` | Channels Settings (tai42\_skeleton.channels.settings) | [Settings](/reference/settings#channelssettings) | [`tai42_skeleton.channels.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `ClassifierSettings` | Classifier Settings (tai42\_kit.llm.settings) | [Settings](/reference/settings#classifiersettings) | [`tai42_kit.llm.settings`](https://github.com/tai42ai/tai42/tree/main/core/kit) |
| `ClientTrustSettings` | Client Trust Settings (tai42\_kit.utils.client\_address) | [Settings](/reference/settings#clienttrustsettings) | [`tai42_kit.utils.client_address`](https://github.com/tai42ai/tai42/tree/main/core/kit) |
| `ConfigModeSettings` | Config Mode Settings (tai42\_skeleton.config.config\_mode) | [Settings](/reference/settings#configmodesettings) | [`tai42_skeleton.config.config_mode`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `ConnectorAdapterSettings` | Connector Adapter Settings (tai42\_skeleton.connectors.settings) | [Settings](/reference/settings#connectoradaptersettings) | [`tai42_skeleton.connectors.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `ConnectorCryptoSecrets` | Connector Crypto Secrets settings (tai42\_skeleton.connectors.settings) | [Settings](/reference/settings#connectorcryptosecrets) | [`tai42_skeleton.connectors.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `ConnectorEngineConfig` | Connector Engine Config settings (tai42\_skeleton.connectors.settings) | [Settings](/reference/settings#connectorengineconfig) | [`tai42_skeleton.connectors.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `ConnectorStoreRedisSettings` | Connector Store Redis Settings (tai42\_skeleton.connectors.settings) | [Settings](/reference/settings#connectorstoreredissettings) | [`tai42_skeleton.connectors.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `ConnectorStoreSettings` | Connector Store Settings (tai42\_skeleton.connectors.settings) | [Settings](/reference/settings#connectorstoresettings) | [`tai42_skeleton.connectors.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `ContextEditingSettings` | Context Editing Settings (tai42\_kit.llm.settings) | [Settings](/reference/settings#contexteditingsettings) | [`tai42_kit.llm.settings`](https://github.com/tai42ai/tai42/tree/main/core/kit) |
| `ContextOverflowSettings` | Context Overflow Settings (tai42\_kit.llm.settings) | [Settings](/reference/settings#contextoverflowsettings) | [`tai42_kit.llm.settings`](https://github.com/tai42ai/tai42/tree/main/core/kit) |
| `ConversationsRedisSettings` | Conversations Redis Settings (tai42\_skeleton.conversations.settings) | [Settings](/reference/settings#conversationsredissettings) | [`tai42_skeleton.conversations.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `ConversationsSettings` | Conversations Settings (tai42\_skeleton.conversations.settings) | [Settings](/reference/settings#conversationssettings) | [`tai42_skeleton.conversations.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `CoreSettings` | Core Settings (tai42\_skeleton.settings.settings) | [Settings](/reference/settings#coresettings) | [`tai42_skeleton.settings.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `EmbeddingSettings` | Embedding Settings (tai42\_kit.llm.settings) | [Settings](/reference/settings#embeddingsettings) | [`tai42_kit.llm.settings`](https://github.com/tai42ai/tai42/tree/main/core/kit) |
| `EnvSecretMarksSettings` | Env Secret Marks Settings (tai42\_skeleton.settings.env\_secret\_marks) | [Settings](/reference/settings#envsecretmarkssettings) | [`tai42_skeleton.settings.env_secret_marks`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `FileLoadingSettings` | File Loading Settings (tai42\_skeleton.template.settings) | [Settings](/reference/settings#fileloadingsettings) | [`tai42_skeleton.template.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `HooksRedisSettings` | Hooks Redis Settings (tai42\_skeleton.hooks.settings) | [Settings](/reference/settings#hooksredissettings) | [`tai42_skeleton.hooks.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `HooksSettings` | Hooks Settings (tai42\_skeleton.hooks.settings) | [Settings](/reference/settings#hookssettings) | [`tai42_skeleton.hooks.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `HostedUiSettings` | Hosted Ui Settings (tai42\_skeleton.plugins.settings) | [Settings](/reference/settings#hosteduisettings) | [`tai42_skeleton.plugins.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `InteractionsRedisSettings` | Interactions Redis Settings (tai42\_skeleton.interactions.settings) | [Settings](/reference/settings#interactionsredissettings) | [`tai42_skeleton.interactions.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `InteractionsSettings` | Interactions Settings (tai42\_skeleton.interactions.settings) | [Settings](/reference/settings#interactionssettings) | [`tai42_skeleton.interactions.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `JqSettings` | Jq Settings (tai42\_kit.utils.data.jq\_util) | [Settings](/reference/settings#jqsettings) | [`tai42_kit.utils.data.jq_util`](https://github.com/tai42ai/tai42/tree/main/core/kit) |
| `LLMProviderSettings` | LLMProvider Settings (tai42\_kit.llm.settings) | [Settings](/reference/settings#llmprovidersettings) | [`tai42_kit.llm.settings`](https://github.com/tai42ai/tai42/tree/main/core/kit) |
| `LLMSettings` | LLMSettings (tai42\_kit.llm.settings) | [Settings](/reference/settings#llmsettings) | [`tai42_kit.llm.settings`](https://github.com/tai42ai/tai42/tree/main/core/kit) |
| `LlmCheckpointConnectionOptions` | Llm Checkpoint Connection Options settings (tai42\_kit.llm.settings) | [Settings](/reference/settings#llmcheckpointconnectionoptions) | [`tai42_kit.llm.settings`](https://github.com/tai42ai/tai42/tree/main/core/kit) |
| `LlmStoreConnectionOptions` | Llm Store Connection Options settings (tai42\_kit.llm.settings) | [Settings](/reference/settings#llmstoreconnectionoptions) | [`tai42_kit.llm.settings`](https://github.com/tai42ai/tai42/tree/main/core/kit) |
| `LoggingSettings` | Logging Settings (tai42\_kit.logging.settings) | [Settings](/reference/settings#loggingsettings) | [`tai42_kit.logging.settings`](https://github.com/tai42ai/tai42/tree/main/core/kit) |
| `MCPClientSettings` | MCPClient Settings (tai42\_kit.clients.settings) | [Settings](/reference/settings#mcpclientsettings) | [`tai42_kit.clients.settings`](https://github.com/tai42ai/tai42/tree/main/core/kit) |
| `MCPDispatchSettings` | MCPDispatch Settings (tai42\_skeleton.settings.mcp\_settings) | [Settings](/reference/settings#mcpdispatchsettings) | [`tai42_skeleton.settings.mcp_settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `MarketplaceSettings` | Marketplace Settings (tai42\_skeleton.marketplace.settings) | [Settings](/reference/settings#marketplacesettings) | [`tai42_skeleton.marketplace.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `MediaIngestCapSettings` | Media Ingest Cap Settings (tai42\_kit.interactions.media\_caps) | [Settings](/reference/settings#mediaingestcapsettings) | [`tai42_kit.interactions.media_caps`](https://github.com/tai42ai/tai42/tree/main/core/kit) |
| `MediaIngestSettings` | Media Ingest Settings (tai42\_skeleton.settings.media\_ingest) | [Settings](/reference/settings#mediaingestsettings) | [`tai42_skeleton.settings.media_ingest`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `MetricsSettings` | Metrics Settings (tai42\_skeleton.routers.metrics\_settings) | [Settings](/reference/settings#metricssettings) | [`tai42_skeleton.routers.metrics_settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `PluginPrefixSettings` | Plugin Prefix Settings (tai42\_skeleton.marketplace.prefix) | [Settings](/reference/settings#pluginprefixsettings) | [`tai42_skeleton.marketplace.prefix`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `PluginsSettings` | Plugins Settings (tai42\_skeleton.plugins.settings) | [Settings](/reference/settings#pluginssettings) | [`tai42_skeleton.plugins.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `RateLimitRedisSettings` | Rate Limit Redis Settings (tai42\_skeleton.settings.rate\_limit) | [Settings](/reference/settings#ratelimitredissettings) | [`tai42_skeleton.settings.rate_limit`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `RateLimitSettings` | Rate Limit Settings (tai42\_skeleton.settings.rate\_limit) | [Settings](/reference/settings#ratelimitsettings) | [`tai42_skeleton.settings.rate_limit`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `RunIndexSettings` | Run Index Settings (tai42\_skeleton.runs.settings) | [Settings](/reference/settings#runindexsettings) | [`tai42_skeleton.runs.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `SamplingSettings` | Sampling Settings (tai42\_skeleton.tools.sampling\_settings) | [Settings](/reference/settings#samplingsettings) | [`tai42_skeleton.tools.sampling_settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `SetupSettings` | Setup Settings (tai42\_skeleton.access\_control.settings) | [Settings](/reference/settings#setupsettings) | [`tai42_skeleton.access_control.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `StatesSettings` | States Settings (tai42\_skeleton.states.db) | [Settings](/reference/settings#statessettings) | [`tai42_skeleton.states.db`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `SubMcpRedisSettings` | Sub Mcp Redis Settings (tai42\_skeleton.sub\_mcp.settings) | [Settings](/reference/settings#submcpredissettings) | [`tai42_skeleton.sub_mcp.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `SubMcpSettings` | Sub Mcp Settings (tai42\_skeleton.sub\_mcp.settings) | [Settings](/reference/settings#submcpsettings) | [`tai42_skeleton.sub_mcp.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `SummarizationMiddlewareSettings` | Summarization Middleware Settings (tai42\_kit.llm.settings) | [Settings](/reference/settings#summarizationmiddlewaresettings) | [`tai42_kit.llm.settings`](https://github.com/tai42ai/tai42/tree/main/core/kit) |
| `TemplateCacheSettings` | Template Cache Settings (tai42\_skeleton.template.settings) | [Settings](/reference/settings#templatecachesettings) | [`tai42_skeleton.template.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `ToolRunsRedisSettings` | Tool Runs Redis Settings (tai42\_skeleton.routers.tool\_runs\_settings) | [Settings](/reference/settings#toolrunsredissettings) | [`tai42_skeleton.routers.tool_runs_settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `ToolRunsSettings` | Tool Runs Settings (tai42\_skeleton.routers.tool\_runs\_settings) | [Settings](/reference/settings#toolrunssettings) | [`tai42_skeleton.routers.tool_runs_settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `TrimmingMiddlewareSettings` | Trimming Middleware Settings (tai42\_kit.llm.settings) | [Settings](/reference/settings#trimmingmiddlewaresettings) | [`tai42_kit.llm.settings`](https://github.com/tai42ai/tai42/tree/main/core/kit) |
| `TurnSettings` | Turn Settings (tai42\_skeleton.settings.turn) | [Settings](/reference/settings#turnsettings) | [`tai42_skeleton.settings.turn`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |
| `UrlGuardSettings` | Url Guard Settings (tai42\_kit.net.url\_guard) | [Settings](/reference/settings#urlguardsettings) | [`tai42_kit.net.url_guard`](https://github.com/tai42ai/tai42/tree/main/core/kit) |
| `WebhookIngressSettings` | Webhook Ingress Settings (tai42\_skeleton.webhooks.settings) | [Settings](/reference/settings#webhookingresssettings) | [`tai42_skeleton.webhooks.settings`](https://github.com/tai42ai/tai42/tree/main/core/skeleton) |

## Agents & extensions

No agents or extensions are registered in the base runtime; agent- and

extension-kind capabilities are listed under Plugins above.


# tai agents
Source: https://docs.tai42.ai/reference/cli/agents

List and run agents.

List and run agents.

```console theme={null}
$ tai agents [OPTIONS] COMMAND [ARGS]...
```

## `tai agents authored-run`

Stream a run of an authored agent (a preset baked over a spec-runnable agent).

Exactly one of `--input` or `--input-file` is required.

Example: `tai agents authored-run my_researcher --input '&#123;"query":"weather"&#125;'`

```console theme={null}
$ tai agents authored-run [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Authored-agent (preset) name. *(required)* |

| Option | Description |
| - | - |
| `--input` `&lt;str&gt;` | The non-baked agent input as a JSON object. |
| `--input-file` `&lt;str&gt;` | Read the agent input JSON object from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --input. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai agents list`

List every registered agent.

Example: `tai agents list`

```console theme={null}
$ tai agents list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai agents run`

Stream a run of an agent, one event frame at a time.

Exactly one of `--input` or `--input-file` is required.

Example: `tai agents run researcher --input '&#123;"query":"weather"&#125;'`

```console theme={null}
$ tai agents run [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Agent registration name. *(required)* |

| Option | Description |
| - | - |
| `--input` `&lt;str&gt;` | The agent input as a JSON object. |
| `--input-file` `&lt;str&gt;` | Read the agent input JSON object from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --input. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai agents spec-runnable`

List the spec-runnable (authorable) agents.

Example: `tai agents spec-runnable`

```console theme={null}
$ tai agents spec-runnable [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai auth
Source: https://docs.tai42.ai/reference/cli/auth

Identity and capability introspection.

Identity and capability introspection.

```console theme={null}
$ tai auth [OPTIONS] COMMAND [ARGS]...
```

## `tai auth claim`

Exchange a one-time claim link for its API key — runs WITHOUT a credential.

Pass the bare token or the whole claim URL; the token is taken from the link's fragment,
under the key the server declares (`GET /api/login/methods`). Pass `-` to read the
token (or claim URL) from stdin, stripped, keeping it off the command line. The exchanged
API key is printed ONCE — capture it now (there is no second exchange; the link is
single-use). A used/unknown/expired token answers the
same `unknown or already used claim token`.

Example: `tai auth claim 'https://host/login#claim=&lt;token&gt;'`

```console theme={null}
$ tai auth claim [OPTIONS] {token}
```

| Argument | Description |
| - | - |
| `token` | A claim token or a full claim URL/fragment (either works), or '-' to read it from stdin (keeping it out of shell history). *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai auth member-actions`

List and invoke the accounts providers' declared member-admin actions.

```console theme={null}
$ tai auth member-actions [OPTIONS] COMMAND [ARGS]...
```

### `tai auth member-actions invoke`

Invoke one declared member action by its opaque key.

The per-action `input` is handed to the action's declared input model and validated
server-side (a declared-field type error is rejected; an unknown key is ignored). The
result is the provider's opaque result — an invite action, say, returns a one-time
sign-in link shown only once, so capture it now.

Example: `tai auth member-actions invoke --action-key &lt;key&gt; --target-handle &lt;handle&gt; --input '&#123;"role": "editor"&#125;'`

```console theme={null}
$ tai auth member-actions invoke [OPTIONS]
```

| Option | Description |
| - | - |
| `--action-key` `&lt;str&gt;` | The opaque catalog key of the action to invoke (from `tai auth member-actions list`). *(required)* |
| `--target-handle` `&lt;str&gt;` | The opaque row handle the action acts on (from the members listing); omit for a page-scoped action. |
| `--input` `&lt;str&gt;` | The per-action input as a JSON object. |
| `--input-file` `&lt;str&gt;` | Read the per-action input JSON object from a file, or '-' for stdin, keeping a secret off the command line (a value on argv leaks via ps and shell history). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

### `tai auth member-actions list`

List every declared member action by its opaque key, label, scope, and destructive flag.

Each registered accounts provider declares its own member-admin actions; the catalog
carries each by an opaque `key` (which `invoke` echoes back), the rendered label, the
placement `scope`, the `destructive` confirm hint, and the input/result JSON schemas
a caller renders a form and a result view from.

Example: `tai auth member-actions list`

```console theme={null}
$ tai auth member-actions list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai auth whoami`

Print the caller's derived capability projection.

Example: `tai auth whoami`

```console theme={null}
$ tai auth whoami [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai backend
Source: https://docs.tai42.ai/reference/cli/backend

Run a tai execution-backend runtime (worker / beat / dashboard).

Run a tai execution-backend runtime (worker / beat / dashboard).


A backend runtime always registers a task backend, so it requires the worker
bus — set TAI\_BUS\_REDIS\_URL. The backend-runtime and server processes must
converge on config reloads, so a busless backend is refused at boot (and again
on any reload that would leave a backend without the bus). A non-file
TAI\_CONFIG\_MODE is likewise refused without the bus.


It also requires the shared hooks registry — set HOOKS\_REDIS\_URL (or
TAI\_DEFAULT\_REDIS\_URL). The events this process raises are matched against
its own registry, and an in-memory one holds none of the hooks registered
through the server, so a backend over it is refused at boot and on reload.

```console theme={null}
$ tai backend [OPTIONS] [EXTRA_ARGS]...
```

| Argument | Description |
| - | - |
| `[EXTRA_ARGS]...` | *(optional)* |

| Option | Description |
| - | - |
| `--manifest-path` `TEXT` | Path to a YAML manifest file (file mode only; ignored under a non-file config mode). |


# tai backup
Source: https://docs.tai42.ai/reference/cli/backup

Export and import server state.

Export and import server state.

```console theme={null}
$ tai backup [OPTIONS] COMMAND [ARGS]...
```

## `tai backup export`

Export the named sections as a backup document (printed to stdout).

Redirect stdout to save it: `tai backup export --section access_control &gt; backup.json`

```console theme={null}
$ tai backup export [OPTIONS]
```

| Option | Description |
| - | - |
| `--section` `&lt;str&gt;` | A section to export (repeatable). *(required)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai backup import`

Import selected sections from a backup document file.

Example: `tai backup import backup.json --section access_control`

```console theme={null}
$ tai backup import [OPTIONS] {file}
```

| Argument | Description |
| - | - |
| `file` | A backup document file. *(required)* |

| Option | Description |
| - | - |
| `--section` `&lt;str&gt;` | A section to import (repeatable). *(required)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai backup sections`

List the registered backup sections.

Example: `tai backup sections`

```console theme={null}
$ tai backup sections [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai catalog
Source: https://docs.tai42.ai/reference/cli/catalog

Print the ecosystem catalog.

Print the ecosystem catalog.

Lists the tai42-skeleton builtins plus every marketplace-listed plugin's items,
queried live from the registry. The network is REQUIRED — offline is a loud error
(no cache, no offline fallback). `--json` (global) emits the raw records for
scripting.

```console theme={null}
$ tai catalog [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai channels
Source: https://docs.tai42.ai/reference/cli/channels

Inspect the registered delivery channels.

Inspect the registered delivery channels.

```console theme={null}
$ tai channels [OPTIONS] COMMAND [ARGS]...
```

## `tai channels list`

List the registered channel names.

Example: `tai channels list`

```console theme={null}
$ tai channels list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai checkpoints
Source: https://docs.tai42.ai/reference/cli/checkpoints

Manage checkpoint retention.

Manage checkpoint retention.

```console theme={null}
$ tai checkpoints [OPTIONS] COMMAND [ARGS]...
```

## `tai checkpoints sweep`

Delete checkpoint threads past their retention horizon (finished, then waiting).

Example: `tai checkpoints sweep`

```console theme={null}
$ tai checkpoints sweep [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai completion
Source: https://docs.tai42.ai/reference/cli/completion

Install shell completion for the tai CLI.

Install shell completion for the tai CLI.

```console theme={null}
$ tai completion [OPTIONS] COMMAND [ARGS]...
```

## `tai completion install`

Emit a shell completion script for the tai CLI.

Pipe it into the shell's completion directory, e.g.
`tai completion install bash &gt; /etc/bash_completion.d/tai`.

```console theme={null}
$ tai completion install [OPTIONS] {shell}:<bash|zsh|fish>
```

| Argument | Description |
| - | - |
| `shell:&lt;bash\|zsh\|fish&gt;` | Shell to emit a completion script for. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai config
Source: https://docs.tai42.ai/reference/cli/config

Read and update server configuration.

Read and update server configuration.

```console theme={null}
$ tai config [OPTIONS] COMMAND [ARGS]...
```

## `tai config env`

Read and update the stored env overrides.

```console theme={null}
$ tai config env [OPTIONS] COMMAND [ARGS]...
```

### `tai config env get`

Read the stored env config and the operator's secret-key marks.

Example: `tai config env get`

```console theme={null}
$ tai config env get [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

### `tai config env set`

Merge KEY=VALUE env overrides and reload the fleet.

A hot-class key is re-read in place. A recycle-class key rolls a worker
recycle across the fleet on a supervised deployment (the response carries the
recycle rows; the worker that took the write recycles itself after replying),
and is refused on a bare deployment, naming the key. The bus URL and a key the
deployment pins are refused on every shape.

Values may come from command-line KEY=VALUE arguments, `--env-file`, and
`--stdin` combined; at least one assignment is required. The same key from
more than one source (or twice in one source) is an error — no silent
precedence. Argv exposes a value via `ps`/shell history, so a secret should
ride `--env-file` or `--stdin`.

Example: `tai config env set LOG_LEVEL=debug --env-file secrets.env`

```console theme={null}
$ tai config env set [OPTIONS] [assignment]...
```

| Argument | Description |
| - | - |
| `assignment...` | KEY=VALUE env overrides to merge (composable with --env-file/--stdin). *(optional)* |

| Option | Description |
| - | - |
| `--env-file` `&lt;file&gt;` | Read KEY=VALUE lines from a file (one per line, split on the first '=', no quote processing; blank and '#' lines skipped) instead of putting a secret on the command line (a value on argv leaks via ps and shell history). |
| `--stdin` | Read the same KEY=VALUE line format from stdin until EOF, keeping a secret off the command line (a value on argv leaks via ps and shell history). *(default: `False`)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai config lint`

Lint config OFFLINE: a manifest file's shape plus required-settings resolution.

Validates the manifest file against the `Manifest` model (a broken manifest
fails loudly with the model error) and checks that every required registered
setting resolves from the environment. No server is started.

Example: `tai config lint config/manifest.yml`

```console theme={null}
$ tai config lint [OPTIONS] [file]
```

| Argument | Description |
| - | - |
| `file` | Manifest file to validate; defaults to \$TAI\_MANIFEST\_PATH when set. *(optional)* |

## `tai config mode`

Read the active config backend mode (`file` or an external provider's mode).

Example: `tai config mode`

```console theme={null}
$ tai config mode [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai config profile`

Manage versioned settings profiles.

```console theme={null}
$ tai config profile [OPTIONS] COMMAND [ARGS]...
```

### `tai config profile apply`

Apply a profile — replace the stored env with its band, reload, and recycle the fleet.

Prints the `&#123;hot, recycle, refused, fanout&#125;` report plus the per-kind `fresh` list (names + worker
identities only, never env values). DESTRUCTIVE: it replaces the whole stored env band.

Example: `tai config profile apply staging`

```console theme={null}
$ tai config profile apply [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Profile name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

### `tai config profile delete`

Soft-delete a profile, keeping its version history for audit.

Example: `tai config profile delete staging`

```console theme={null}
$ tai config profile delete [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Profile name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

### `tai config profile diff`

Preview a profile against the CURRENT stored env — `&#123;added, removed, changed, recycle_keys, refused_keys&#125;`.

Values are real; this is a preview, not the apply report.

Example: `tai config profile diff staging`

```console theme={null}
$ tai config profile diff [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Profile name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

### `tai config profile list`

List the settings profiles (reserved `@` snapshots excluded).

Example: `tai config profile list`

```console theme={null}
$ tai config profile list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

### `tai config profile rollback`

Re-point a profile's active version to `version` (a store re-point).

The live process is realigned by a later apply, not by this.

Example: `tai config profile rollback staging 2`

```console theme={null}
$ tai config profile rollback [OPTIONS] {name} {version}
```

| Argument | Description |
| - | - |
| `name` | Profile name. *(required)* |
| `version` | Target version to make active. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

### `tai config profile set`

Create or update a profile (whole-body replace).

The env band is the given KEY=VALUE entries; `--secret-key` marks which keys are secret. A reserved
`@`-prefixed name is rejected up front.

The band may come from command-line KEY=VALUE arguments, `--env-file`, and
`--stdin` combined; with no source at all the band is empty (a whole-body
replace clears the stored env), but a given `--env-file` or `--stdin` that
yields no assignment is an error. The same key from more than one source (or
twice in one source) is an error — no silent precedence. Argv exposes a value
via `ps`/shell history, so a secret should ride `--env-file` or `--stdin`.

Example: `tai config profile set staging LOG_LEVEL=debug --env-file secrets.env --secret-key API_KEY`

```console theme={null}
$ tai config profile set [OPTIONS] {name} [assignment]...
```

| Argument | Description |
| - | - |
| `name` | Profile name (a leading '@' is reserved). *(required)* |
| `assignment...` | KEY=VALUE entries forming the profile's WHOLE env band (composable with --env-file/--stdin). *(optional)* |

| Option | Description |
| - | - |
| `--description` `&lt;str&gt;` | The profile's human description. *(default: \`)* |
| `--secret-key` `&lt;str&gt;` | An env key to mark secret for display masking (repeatable). |
| `--env-file` `&lt;file&gt;` | Read KEY=VALUE lines from a file (one per line, split on the first '=', no quote processing; blank and '#' lines skipped) instead of putting a secret on the command line (a value on argv leaks via ps and shell history). |
| `--stdin` | Read the same KEY=VALUE line format from stdin until EOF, keeping a secret off the command line (a value on argv leaks via ps and shell history). *(default: `False`)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

### `tai config profile show`

Show a profile's active body — `&#123;description, env, secret_keys&#125;` with real env values.

This authed door round-trips values; masking is display-side only.

Example: `tai config profile show staging`

```console theme={null}
$ tai config profile show [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Profile name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

### `tai config profile versions`

List a profile's version history, or — with `--version` — show one version's full body.

Full bodies carry real env values; this door is secret-fenced.

Example: `tai config profile versions staging` / `... versions staging --version 3`

```console theme={null}
$ tai config profile versions [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Profile name. *(required)* |

| Option | Description |
| - | - |
| `--version` `&lt;int&gt;` | Show this one version's full body instead of the history list. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai config reload`

Soft-restart this process from its manifest, fanning out to every worker.

Refreshes env, resets settings caches, and re-initializes from the manifest
in-process (no pod restart), then propagates to the fleet; `--target` restricts
the fan-out to named workers.

Each worker's row names the recycle-class keys awaiting a respawn
(`awaiting_respawn`): the soft restart carries every hot key in place, and
those keys take effect only when that worker is respawned through the
deployment's supervisor (on a bare deployment, a server restart).

Example: `tai config reload`

```console theme={null}
$ tai config reload [OPTIONS]
```

| Option | Description |
| - | - |
| `--target` `&lt;str&gt;` | A worker slot name to restrict the reload to (e.g. serve-1; repeatable). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai config settings-schema`

List the registered settings groups with their resolved field values.

Example: `tai config settings-schema --json`

```console theme={null}
$ tai config settings-schema [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai connectors
Source: https://docs.tai42.ai/reference/cli/connectors

Manage connector providers and connections.

Manage connector providers and connections.

```console theme={null}
$ tai connectors [OPTIONS] COMMAND [ARGS]...
```

## `tai connectors add-server`

Add an MCP server that signs in with OAuth as a connector provider.

Example: `tai connectors add-server https://mcp.example.com/mcp --name "Team tools"`

```console theme={null}
$ tai connectors add-server [OPTIONS] {url}
```

| Argument | Description |
| - | - |
| `url` | The address of the MCP server to add. *(required)* |

| Option | Description |
| - | - |
| `--id` `&lt;str&gt;` | The provider id (default: suggested from the host). |
| `--name` `&lt;str&gt;` | The display name. |
| `--description` `&lt;str&gt;` | A description. |
| `--icon-url` `&lt;str&gt;` | An https URL of an icon. |
| `--category` `&lt;str&gt;` | The catalog category (default: other). |
| `--scope` `&lt;str&gt;` | A scope to request (repeatable; default: what the server lists). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai connectors connect`

Start a connection flow; prints the authorize URL (or the created connection).

Example: `tai connectors connect google --alias work --sub-service gmail`

```console theme={null}
$ tai connectors connect [OPTIONS] {provider}
```

| Argument | Description |
| - | - |
| `provider` | Provider id. *(required)* |

| Option | Description |
| - | - |
| `--alias` `&lt;str&gt;` | A unique alias for the new connection. *(required)* |
| `--sub-service` `&lt;str&gt;` | An enabled sub-service (repeatable). *(required)* |
| `--config` `&lt;str&gt;` | Provider config values as a JSON object. |
| `--config-file` `&lt;str&gt;` | Read the provider config values from a file, or from stdin when the path is '-', which keeps provider secrets off the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --config. |
| `--return-url` `&lt;str&gt;` | Where to return after the flow completes (omitted: the deployment's connectors page). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai connectors connections`

List the installed connections (no secrets).

Example: `tai connectors connections`

```console theme={null}
$ tai connectors connections [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai connectors disconnect`

Disconnect (delete) a connection.

Example: `tai connectors disconnect conn_123`

```console theme={null}
$ tai connectors disconnect [OPTIONS] {connection_id}
```

| Argument | Description |
| - | - |
| `connection_id` | Connection id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai connectors discover`

Look up an MCP server's sign-in: every sign-in service it lists and the redirect URI to register.

Example: `tai connectors discover https://mcp.example.com/mcp`

```console theme={null}
$ tai connectors discover [OPTIONS] [url]
```

| Argument | Description |
| - | - |
| `url` | The address of the MCP server to look up. *(optional)* |

| Option | Description |
| - | - |
| `--provider` `&lt;str&gt;` | Look up the server of this discovered provider instead. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai connectors get`

Get one connection.

Example: `tai connectors get conn_123`

```console theme={null}
$ tai connectors get [OPTIONS] {connection_id}
```

| Argument | Description |
| - | - |
| `connection_id` | Connection id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai connectors providers`

List the available connector providers.

Example: `tai connectors providers`

```console theme={null}
$ tai connectors providers [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai connectors reconnect`

Start a reconnect (re-authorize) flow for an existing connection.

Example: `tai connectors reconnect conn_123 --sub-service gmail`

```console theme={null}
$ tai connectors reconnect [OPTIONS] {connection_id}
```

| Argument | Description |
| - | - |
| `connection_id` | Connection id. *(required)* |

| Option | Description |
| - | - |
| `--sub-service` `&lt;str&gt;` | An enabled sub-service (repeatable). *(required)* |
| `--return-url` `&lt;str&gt;` | Where to return after the flow completes (omitted: the deployment's connectors page). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai connectors reencrypt-tokens`

Re-encrypt every stored token and client credential under the current CONNECTORS\_KEK.

Run after rotating CONNECTORS\_KEK (old key moved to CONNECTORS\_KEK\_PREVIOUS) to
converge every connection token blob and every stored OAuth client blob onto the
new key so the previous key can be retired.

Example: `tai connectors reencrypt-tokens`

```console theme={null}
$ tai connectors reencrypt-tokens [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai connectors remove-server`

Remove a provider added by its address, and its stored client credentials.

Example: `tai connectors remove-server mcp_example_com`

```console theme={null}
$ tai connectors remove-server [OPTIONS] {provider_id}
```

| Argument | Description |
| - | - |
| `provider_id` | Provider id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai connectors set-client`

Set the client credentials of an app registered by hand for a discovered provider.

Example: `tai connectors set-client mcp_example_com --client-id app --client-secret-file - --issuer URL`

```console theme={null}
$ tai connectors set-client [OPTIONS] {provider_id}
```

| Argument | Description |
| - | - |
| `provider_id` | Provider id. *(required)* |

| Option | Description |
| - | - |
| `--client-id` `&lt;str&gt;` | The client id of the app registered by hand. *(required)* |
| `--client-secret-file` `&lt;str&gt;` | Read the client secret from a file, or from stdin when the path is '-' (never an argument: a value on argv leaks via ps and shell history). Leave out for an app without a secret. |
| `--auth-method` `&lt;str&gt;` | client\_secret\_post, client\_secret\_basic or none (default: chosen from the sign-in service). |
| `--issuer` `&lt;str&gt;` | The sign-in service the app belongs to; the secret is sent to no other. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai connectors sub-services`

Change a connection's enabled sub-services.

Example: `tai connectors sub-services conn_123 --sub-service gmail --sub-service calendar`

```console theme={null}
$ tai connectors sub-services [OPTIONS] {connection_id}
```

| Argument | Description |
| - | - |
| `connection_id` | Connection id. *(required)* |

| Option | Description |
| - | - |
| `--sub-service` `&lt;str&gt;` | The desired enabled sub-service (repeatable). *(required)* |
| `--return-url` `&lt;str&gt;` | Where to return if consent is required (omitted: the deployment's connectors page). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai conversations
Source: https://docs.tai42.ai/reference/cli/conversations

Manage conversation routes.

Manage conversation routes.

```console theme={null}
$ tai conversations [OPTIONS] COMMAND [ARGS]...
```

## `tai conversations config-delete`

Delete a per-target conversation config by (target\_kind, target\_name).

Example: `tai conversations config-delete agent assistant`

```console theme={null}
$ tai conversations config-delete [OPTIONS] {target_kind} {target_name}
```

| Argument | Description |
| - | - |
| `target_kind` | Target kind: 'agent' or 'tool'. *(required)* |
| `target_name` | The agent or tool name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations config-get`

Show one per-target conversation config by (target\_kind, target\_name).

Example: `tai conversations config-get agent assistant`

```console theme={null}
$ tai conversations config-get [OPTIONS] {target_kind} {target_name}
```

| Argument | Description |
| - | - |
| `target_kind` | Target kind: 'agent' or 'tool'. *(required)* |
| `target_name` | The agent or tool name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations config-list`

List the per-target conversation configs (multichannel opt-in + first-contact greeting).

Example: `tai conversations config-list`

```console theme={null}
$ tai conversations config-list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations config-set`

Create or replace a per-target conversation config.

An UPSERT — a config for that (target\_kind, target\_name) is REPLACED if it exists
(`created` is `false` for a replace). The target must EXIST. `--greeting-template`
may reference at most the `&#123;pairing_code&#125;` placeholder; omit it (or pass an empty
value is refused) for no greeting.

Example: `tai conversations config-set agent assistant --multichannel \\ --greeting-template 'Hi! Pair another channel with &#123;pairing_code&#125;'`

```console theme={null}
$ tai conversations config-set [OPTIONS] {target_kind} {target_name}
```

| Argument | Description |
| - | - |
| `target_kind` | Target kind: 'agent' or 'tool' (must exist). *(required)* |
| `target_name` | The agent or tool name (must exist). *(required)* |

| Option | Description |
| - | - |
| `--multichannel` / `--no-multichannel` | Opt the target into person linking. *(default: `False`)* |
| `--greeting-template` `&lt;str&gt;` | First-contact greeting; may reference the \{pairing\_code} placeholder. Omit for no greeting. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations create`

Create or replace a conversation route.

An UPSERT — a name that already exists is REPLACED, rebinding its `execution_key`
along with everything else (`created` is `false` for a replace). A `door=api`
route's `callback_secret` is minted server-side and shown ONCE in the result; it
signs the delivery callback and is never re-readable. There is no check that you can
run the target — the execution key's live grants bound the turn. Either target kind may map the
message to the run's kwargs (`--start-expr`), build the extras mapping handed to the started
target (`--extras-expr`), cancel or resume its parked interactions
(`--cancel-expr`/`--resume-expr`) and map the result to the reply (`--reply-expr`); a reply
of null/blank sends nothing.

Example: `tai conversations create chat-line --door channel --target-name relay \\ --execution-key svc --channel twilio --identity +15550001111`

```console theme={null}
$ tai conversations create [OPTIONS] {route_name}
```

| Argument | Description |
| - | - |
| `route_name` | Route name — a slug \[a-z0-9-]+ (the thread-key handle). *(required)* |

| Option | Description |
| - | - |
| `--door` `&lt;str&gt;` | Inbound door: 'api' or 'channel'. *(required)* |
| `--target-name` `&lt;str&gt;` | The agent or tool the turn runs (must exist). *(required)* |
| `--execution-key` `&lt;str&gt;` | The api-key user id the turn runs AS; you must own it (or be admin), tokenless-evaluable. *(required)* |
| `--target-kind` `&lt;str&gt;` | What the turn runs: 'agent' or 'tool'. *(default: `agent`)* |
| `--start-expr` `&lt;str&gt;` | jq mapping the inbound turn payload to the started run's kwargs. |
| `--cancel-expr` `&lt;str&gt;` | jq naming the run's parked interactions to cancel (\$parked bound). |
| `--resume-expr` `&lt;str&gt;` | jq naming the run's parked interactions to resume/take (\$parked bound). |
| `--extras-expr` `&lt;str&gt;` | jq building the extras mapping handed to the started target. |
| `--reply-expr` `&lt;str&gt;` | jq mapping the run's result to the reply ($turn/$asks/\$parked bound). |
| `--initial-mode` `&lt;str&gt;` | Default control mode when a thread has no override: 'agent' or 'manual'. *(default: `agent`)* |
| `--channel` `&lt;str&gt;` | door=channel: the channel registry name (e.g. twilio). |
| `--identity` `&lt;str&gt;` | door=channel: the medium address we are texted at. |
| `--callback-url` `&lt;str&gt;` | door=api: optional https answer-delivery URL; without one the caller polls the message. |
| `--turns-per-hour-override` `&lt;int&gt;` | Per-route override (positive) of the global per-address turns/hour cap; unset uses the global rate. |
| `--reply-error` `&lt;str&gt;` | Reply sent when a turn fails and the target gave no reply of its own. Unset sends the built-in English text. |
| `--reply-slow-down` `&lt;str&gt;` | Reply sent when an address is over the turn cap. Unset sends the built-in English text. |
| `--reply-pairing-linked` `&lt;str&gt;` | Reply sent when a pair code was redeemed and the two persons merged. Unset sends the built-in English text. |
| `--reply-pairing-unlinked` `&lt;str&gt;` | Reply sent when /unlink detached the address. Unset sends the built-in English text. |
| `--reply-pairing-not-linked` `&lt;str&gt;` | Reply sent when /unlink came from an address linked to nothing. Unset sends the built-in English text. |
| `--reply-pairing-code-invalid` `&lt;str&gt;` | Reply sent when a pair-code redeem was refused. Unset sends the built-in English text. |
| `--reply-pairing-code` `&lt;str&gt;` | The /link reply template; must contain \{pairing\_code} and may contain \{expires\_at}. Unset sends the built-in English text. |
| `--reply-pairing-link-unavailable` `&lt;str&gt;` | Reply sent when a pair-code redeem met a person being deleted. Unset sends the built-in English text. |
| `--reply-pairing-unlink-unavailable` `&lt;str&gt;` | Reply sent when /unlink met a person being deleted. Unset sends the built-in English text. |
| `--reply-rejected-unsupported-type` `&lt;str&gt;` | Notice for an inbound message the channel cannot bridge. Unset sends the built-in English text. |
| `--reply-rejected-too-large` `&lt;str&gt;` | Notice for an inbound file over the size cap. Unset sends the built-in English text. |
| `--reply-rejected-could-not-receive` `&lt;str&gt;` | Notice for an inbound file the channel could not fetch. Unset sends the built-in English text. |
| `--locale` `&lt;str&gt;` | Default BCP 47 locale for templated reply parts when a turn states none; unset means no default. |
| `--overlap-running` `&lt;str&gt;` | When a newer participant message arrives while a turn is running on the same thread: 'continue' leaves it running (one turn per message), 'cancel' cancels it cooperatively in favour of the newer message; unset uses the server default ('continue'). |
| `--overlap-deliver` `&lt;str&gt;` | What a turn carries: 'one' exactly one message per turn, 'all' every message accepted since the last turn started, in order, as one turn; unset uses the server default ('one'). |
| `--overlap-settle-seconds` `&lt;int&gt;` | Seconds a turn waits after its lead message is accepted before it starts, so a burst inside the window rides one turn (0..30); a value above 0 requires --overlap-deliver all or --overlap-running cancel. Unset uses the server default (0, no window). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations delete`

Delete a conversation route by name.

Example: `tai conversations delete chat-line`

```console theme={null}
$ tai conversations delete [OPTIONS] {route_name}
```

| Argument | Description |
| - | - |
| `route_name` | Route name (slug). *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations delete-person`

Erase a linked person ENTIRELY — its aggregated thread, its person row and every address index.

The aggregated `bridge:@person:&lt;id&gt;` thread carries the agent checkpoint, answer records,
thread indexes and mode override across every route it spans; the person row and every
address→person index mapping are dropped too. Every person it absorbed by a link is cleared
with it: that person's aggregated thread, and every thread on any route that only this person
and the persons it absorbed wrote in. A thread another person also wrote in is left to them.
The answer's `absorbed_person_ids` lists the absorbed ids it cleared, so their run traces
can be deleted.
Idempotent: erasing an already-gone person is not an error (`erased: false`), and its
aggregated checkpoint is forgotten regardless. An id a link absorbed into another person is
refused (409, naming that person in `absorbed_into_person_id`: erase that one). A turn in
flight on a thread the erase clears is refused (409, retry once it drains), and so is a write
by the person that lands in a thread the erase had not reached, in its last moment (409: the
erase stays marked, and a retry finishes it and clears that thread too). The same write grant
that forgets a thread erases a person.

Example: `tai conversations delete-person 4f1c0e2a-...`

```console theme={null}
$ tai conversations delete-person [OPTIONS] {person_id}
```

| Argument | Description |
| - | - |
| `person_id` | Person id (uuid4). *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations delete-thread`

Forget one conversation thread so a later message on the same address starts a fresh memory.

Forgetting clears the thread's agent checkpoint, its answer records and its thread indexes.
Forgetting is absolute: a valid id on its own route always succeeds, reporting
`removed: 0` when nothing was left to clear (an aged-out or never-seen thread), never a
404 — the agent memory is forgotten regardless. A route-keyed id must carry the route's
`bridge:&lt;route_name&gt;:` prefix, else it is refused (400); a person thread not on the named
route is a 404. A turn in flight on the thread is refused (409, retry once it drains). The
same write grant that creates a route lets you delete routes and forget threads.

The thread id rides the query string, so an api-door id — which carries a percent-encoded
principal — reaches the door spelled exactly as the listing showed it.

Example: `tai conversations delete-thread chat-line bridge:chat-line:+15550001111`

```console theme={null}
$ tai conversations delete-thread [OPTIONS] {route_name} {thread_id}
```

| Argument | Description |
| - | - |
| `route_name` | Route name (slug). *(required)* |
| `thread_id` | Thread id (e.g. bridge:chat:+15550001111). *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations failed`

List answer records whose delivery ended failed (admin only).

Example: `tai conversations failed`

```console theme={null}
$ tai conversations failed [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations get`

Show one conversation route by name (its callback\_secret is withheld).

Example: `tai conversations get chat-line`

```console theme={null}
$ tai conversations get [OPTIONS] {route_name}
```

| Argument | Description |
| - | - |
| `route_name` | Route name (slug). *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations get-message`

Read one conversation answer record.

Any holder of the conversations read grant reads any record on the route, whichever door it
arrived through; a non-admin caller gets the caller-safe projection, with the internal error
detail withheld.

Example: `tai conversations get-message chat-line 4f1c...`

```console theme={null}
$ tai conversations get-message [OPTIONS] {route_name} {message_id}
```

| Argument | Description |
| - | - |
| `route_name` | Route name (slug). *(required)* |
| `message_id` | Answer record message id (uuid4). *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations get-person`

Read a person — its identity, folded addresses and stored `locale`.

`locale` is the BCP 47 tag the rendering layer resolves text against, or `null` when
none is known.

Example: `tai conversations get-person 4f1c0e2a-...`

```console theme={null}
$ tai conversations get-person [OPTIONS] {person_id}
```

| Argument | Description |
| - | - |
| `person_id` | Person id (uuid4). *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations list`

List conversation routes (each row's callback\_secret is withheld).

Example: `tai conversations list`

```console theme={null}
$ tai conversations list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations mode-get`

Show a thread's control mode and where it comes from.

The mode is a per-thread override when one is set, otherwise the route's default.

Example: `tai conversations mode-get chat-line bridge:chat-line:+15550001111`

```console theme={null}
$ tai conversations mode-get [OPTIONS] {route_name} {thread_id}
```

| Argument | Description |
| - | - |
| `route_name` | Route name (slug). *(required)* |
| `thread_id` | Thread id (e.g. bridge:chat-line:+15550001111). *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations mode-set`

Set a thread's control mode override.

`agent` runs the target turn on the next inbound message; `manual` suppresses it so an
operator answers by hand, while platform control turns (pairing, greeting) still run. The
same write grant that forgets threads sets a thread's mode.

Example: `tai conversations mode-set chat-line bridge:chat-line:+15550001111 manual`

```console theme={null}
$ tai conversations mode-set [OPTIONS] {route_name} {thread_id} {mode}
```

| Argument | Description |
| - | - |
| `route_name` | Route name (slug). *(required)* |
| `thread_id` | Thread id (e.g. bridge:chat-line:+15550001111). *(required)* |
| `mode` | Control mode: 'agent' or 'manual'. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations search`

Search a route's answer records by text, across all its threads (admin only).

Matches an inbound message or an answer containing `q`. A bounded server-side scan, so a
page that spent its budget reports `truncated: true` (matches may lie beyond it).

Example: `tai conversations search chat-line --q widget`

```console theme={null}
$ tai conversations search [OPTIONS] {route_name}
```

| Argument | Description |
| - | - |
| `route_name` | Route name (slug). *(required)* |

| Option | Description |
| - | - |
| `--q` `&lt;str&gt;` | The text to search the route's records for. *(required)* |
| `--page` `&lt;int&gt;` | Page number, from 1. *(default: `1`)* |
| `--page-size` `&lt;int&gt;` | Records per page (capped server-side). *(default: `50`)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations send`

Send a message BY HAND into one thread, delivered as the route identity — no turn runs.

Allowed in either mode and it never flips the mode. A route-keyed id must carry the
route's `bridge:&lt;route_name&gt;:` prefix (else 400); a person thread not on the named route
is a 404. `--address` picks the send target on a linked person's aggregated thread and
must be one of the person's addresses; without it the target is the thread's newest
record, and an empty person thread with no `--address` is a 400. A target that keeps
thread memory gets the message appended to that memory as an assistant reply; a target
with no thread memory skips it.

The thread id rides the body, so an api-door id — which carries a percent-encoded
principal — reaches the door spelled exactly as the listing showed it.

Example: `tai conversations send chat-line bridge:chat-line:+15550001111 --text 'On it.'`

```console theme={null}
$ tai conversations send [OPTIONS] {route_name} {thread_id}
```

| Argument | Description |
| - | - |
| `route_name` | Route name (slug). *(required)* |
| `thread_id` | Thread id (e.g. bridge:chat-line:+15550001111). *(required)* |

| Option | Description |
| - | - |
| `--text` `&lt;str&gt;` | The message to send into the thread. *(required)* |
| `--address` `&lt;str&gt;` | Send target on a linked person's thread (one of the person's addresses). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations set-person-locale`

Set (or clear) a person's stored `locale`.

`locale` is the operator override the rendering layer resolves text against, winning over
the channel-seeded value on every later turn. Omit `locale` to clear it back to
no-locale-known. The same write grant that forgets a thread sets a person's locale.

Example: `tai conversations set-person-locale 4f1c0e2a-... he-IL`

```console theme={null}
$ tai conversations set-person-locale [OPTIONS] {person_id} [locale]
```

| Argument | Description |
| - | - |
| `person_id` | Person id (uuid4). *(required)* |
| `locale` | BCP 47 tag (e.g. he-IL); omit to CLEAR the stored locale. *(optional)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations threads`

List a route's conversation threads, newest activity first (admin only).

`--status` and `--address` filter the listing with a bounded server-side scan; a page
that spent its scan budget reports `truncated: true` (matches may lie beyond it). An
unknown `--status` is refused (400).

Example: `tai conversations threads chat-line --page 1 --status failed`

```console theme={null}
$ tai conversations threads [OPTIONS] {route_name}
```

| Argument | Description |
| - | - |
| `route_name` | Route name (slug). *(required)* |

| Option | Description |
| - | - |
| `--page` `&lt;int&gt;` | Page number, from 1. *(default: `1`)* |
| `--page-size` `&lt;int&gt;` | Threads per page (capped server-side). *(default: `50`)* |
| `--status` `&lt;str&gt;` | Keep only threads whose newest record's delivery\_status is this one. |
| `--address` `&lt;str&gt;` | Keep only threads whose id client-address suffix contains this substring. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai conversations transcript`

Read one thread's transcript.

Any holder of the conversations read grant reads any thread's transcript on the route; an
unknown thread or route is a plain 404.

`--order asc` (the default) reads oldest first; `--order desc` reads newest first,
so page 1 always holds the latest messages — the order a live tail wants. The window
pages that order from its own end. `--q` filters to matching records with a bounded
server-side scan; a page that spent its budget reports `truncated: true`, and under
`--q` a thread with no match reads as an empty page rather than a 404.

The thread id rides the query string, so an api-door id — which carries a
percent-encoded principal — reaches the door spelled exactly as the listing showed it.

Example: `tai conversations transcript chat-line bridge:chat-line:+15550001111`

```console theme={null}
$ tai conversations transcript [OPTIONS] {route_name} {thread_id}
```

| Argument | Description |
| - | - |
| `route_name` | Route name (slug). *(required)* |
| `thread_id` | Thread id (e.g. bridge:chat-line:+15550001111). *(required)* |

| Option | Description |
| - | - |
| `--page` `&lt;int&gt;` | Page number, from 1. *(default: `1`)* |
| `--page-size` `&lt;int&gt;` | Records per page (capped server-side). *(default: `50`)* |
| `--order` `&lt;str&gt;` | Record order: 'asc' (oldest first) or 'desc'. *(default: `asc`)* |
| `--q` `&lt;str&gt;` | Keep only records whose inbound text or answer contains this substring. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai db
Source: https://docs.tai42.ai/reference/cli/db

Apply and inspect database migrations.

Apply and inspect database migrations.

```console theme={null}
$ tai db [OPTIONS] COMMAND [ARGS]...
```

## `tai db migrate`

Apply every pending migration across all discovered components.

Discovery covers the skeleton chains plus every plugin that declares one: the plugins
the deployment LOADS via the manifest, and the marketplace-installed and
prefix-installed plugins. `--plan` lists what would be applied and changes nothing.
Idempotent: with nothing pending it reports so and exits 0. Exits non-zero, after
reporting what ran, when a declared migration chain was skipped (its override binding
is unset). Manifest-optional: an absent manifest contributes no manifest-loaded chains
and migrate proceeds on the skeleton, store, and prefix chains. Loud on a connection
failure, an unconfigured connection, a rewritten (checksum-mismatched) chain, or a
manifest that exists but is malformed or invalid.

```console theme={null}
$ tai db migrate [OPTIONS]
```

| Option | Description |
| - | - |
| `--plan` | Show pending migrations without applying them. *(default: `False`)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai db status`

Report each component's applied / pending / checksum verdict.

Reports every discovered component: the skeleton chains plus every plugin that declares
one — the plugins the deployment LOADS via the manifest, and the marketplace-installed
and prefix-installed plugins. Exits non-zero when any component has pending migrations
or a checksum mismatch, or when a declared migration chain was skipped (its override
binding is unset), so it doubles as a CI / pre-deploy gate. Manifest-optional: an absent
manifest contributes no manifest-loaded chains and status reports the skeleton, store,
and prefix chains. Loud on a connection failure, an unconfigured connection, or a
manifest that exists but is malformed or invalid.

```console theme={null}
$ tai db status [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai doctor
Source: https://docs.tai42.ai/reference/cli/doctor

Run read-only health diagnostics against the environment.

Run read-only health diagnostics against the environment.

Probes Python version, config mode, Postgres and Redis connectivity, and
whether the schema is applied. Purely read-only. Credentials are redacted:
connection-URL userinfo is masked and no DSN is echoed. Exits non-zero when
any dependency check fails.

```console theme={null}
$ tai doctor [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai extensions
Source: https://docs.tai42.ai/reference/cli/extensions

Browse the global tool-extension catalog.

Browse the global tool-extension catalog.

```console theme={null}
$ tai extensions [OPTIONS] COMMAND [ARGS]...
```

## `tai extensions list`

List every registered extension in the global catalog.

Example: `tai extensions list`

```console theme={null}
$ tai extensions list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai fleet
Source: https://docs.tai42.ai/reference/cli/fleet

Inspect the execution backend and drive fleet ops.

Inspect the execution backend and drive fleet ops.

```console theme={null}
$ tai fleet [OPTIONS] COMMAND [ARGS]...
```

## `tai fleet info`

Show the registered backend's identity (or the empty state).

Example: `tai fleet info`

```console theme={null}
$ tai fleet info [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai fleet reload-config`

Soft-restart the worker fleet — all of them, or only `--target` ones.

The response is the per-worker fleet report (one row per worker with its
reload outcome).

Each worker's row names the recycle-class keys awaiting a respawn
(`awaiting_respawn`): the soft restart carries every hot key in place, and
those keys take effect only when that worker is respawned through the
deployment's supervisor (on a bare deployment, a server restart).

Example: `tai fleet reload-config --target serve-1`

```console theme={null}
$ tai fleet reload-config [OPTIONS]
```

| Option | Description |
| - | - |
| `--target` `&lt;str&gt;` | A worker slot name to restrict the reload to (e.g. serve-1; repeatable). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai fleet workers`

List the live worker fleet — every process on the bus.

Example: `tai fleet workers`

```console theme={null}
$ tai fleet workers [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai hooks
Source: https://docs.tai42.ai/reference/cli/hooks

Register and inspect webhook hooks.

Register and inspect webhook hooks.

```console theme={null}
$ tai hooks [OPTIONS] COMMAND [ARGS]...
```

## `tai hooks create-trigger-link`

Mint a trigger link — a PUBLIC URL that fires the topic's hooks.

`--execution-key` is REQUIRED: the api-key identity the link's DISPATCH is gated on,
so revoking or disabling that key kills the link (each hook the link fires is
authorized against its OWN bound key). Bind your own identity or a key you own (an
admin may bind any); its policy condition must be evaluable without a presented token.
Exactly ONE of `--ttl SECONDS` or `--permanent` is required — expiry is an explicit
choice. `--require-api-key` also demands an authenticated caller, enforced only where
access control is ENABLED; it does not touch the topic's own
`/universal_webhook/&#123;topic&#125;` door, which stays public by its own route declaration —
a verifier binding is its only lock. `--params` merges BELOW each fired
hook's static tool\_kwargs, so a link never restates a pinned argument. The token is
shown ONCE, in the printed absolute URL; the link is MULTI-use and revocable by name
(`tai hooks delete-trigger-link NAME`). Regenerate = revoke + create.

Example: `tai hooks create-trigger-link events --execution-key svc --ttl 3600 --params '&#123;"p":"hi"&#125;'`

```console theme={null}
$ tai hooks create-trigger-link [OPTIONS] {topic}
```

| Argument | Description |
| - | - |
| `topic` | The hook topic the link fires. *(required)* |

| Option | Description |
| - | - |
| `--execution-key` `&lt;str&gt;` | The api-key user id the link's dispatch is gated on; revoking it kills the link. *(required)* |
| `--name` `&lt;str&gt;` | Link name (the revocation handle); a unique name is generated when omitted. |
| `--ttl` `&lt;int&gt;` | Link lifetime in seconds (a timed link). |
| `--permanent` | Mint a link that never expires. *(default: `False`)* |
| `--require-api-key` | Also demand an api key the route gate admits at the door, beside the token (enforced only where access control is enabled). *(default: `False`)* |
| `--params` `&lt;str&gt;` | Per-link tool\_kwargs as a JSON object, filling only the arguments a hook leaves unpinned. |
| `--params-file` `&lt;str&gt;` | Read the params JSON object from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --params. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai hooks delete`

Unregister a hook by name.

Example: `tai hooks delete h1`

```console theme={null}
$ tai hooks delete [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Hook name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai hooks delete-trigger-link`

Revoke a trigger link by name.

The revocation is immediate and durable: a restored backup cannot re-arm it.

Example: `tai hooks delete-trigger-link my-wall-qr`

```console theme={null}
$ tai hooks delete-trigger-link [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Trigger link name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai hooks delete-verifier`

Remove a topic's verifier binding.

ADMIN-ONLY: a `hooks`-write role is fenced out of this door and reads a bare 403.

Unbinding REOPENS the topic's public `/universal_webhook/&#123;topic&#125;` ingress door to
anyone who knows the topic name, at which point every hook on it fires under its bound
execution key for an anonymous caller.

Example: `tai hooks delete-verifier github`

```console theme={null}
$ tai hooks delete-verifier [OPTIONS] {topic}
```

| Argument | Description |
| - | - |
| `topic` | Hook topic. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai hooks list`

List registered hooks.

The per-topic verifier bindings and each topic's derived `trigger_auth` ride the `--json` body.

Example: `tai hooks list --topic github`

```console theme={null}
$ tai hooks list [OPTIONS]
```

| Option | Description |
| - | - |
| `--topic` `&lt;str&gt;` | Filter to one topic. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai hooks register`

Register a hook from a `HookRegister` JSON body.

Exactly one of `--params` or `--params-file` is required.

The body REQUIRES an `execution_key` — the api-key user id the hook fires as. Bind
your own identity or a key you own (an admin may bind any); its policy condition must
be evaluable without a presented token.

An existing name is REPLACED, `execution_key` included, and `registered` is
`true` either way — run `tai hooks list` first to see whether the name is taken.

A hook is a parkable-driving door: an optional `start_expr` builds the fired tool's
kwargs over the event payload (e.g. `"start_expr":".body"`), and `cancel_expr` /
`resume_expr` / `extras_expr` act on the run's parked interactions and its extras.

Example: `tai hooks register --params '&#123;"name":"h1","topic":"gh","tool":"notify","execution_key":"svc"&#125;'`

```console theme={null}
$ tai hooks register [OPTIONS]
```

| Option | Description |
| - | - |
| `--params` `&lt;str&gt;` | The hook register body as a JSON object. |
| `--params-file` `&lt;str&gt;` | Read the params JSON object from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --params. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai hooks runs`

List, retry or discard hook runs.

```console theme={null}
$ tai hooks runs [OPTIONS] COMMAND [ARGS]...
```

### `tai hooks runs discard`

Discard a failed hook run for good.

Example: `tai hooks runs discard RUN_ID --yes`

```console theme={null}
$ tai hooks runs discard [OPTIONS] {ID}
```

| Argument | Description |
| - | - |
| `ID` | The failed hook run's id. *(required)* |

| Option | Description |
| - | - |
| `--yes` | Confirm: its hook never runs again for that event. *(default: `False`)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

### `tai hooks runs list`

List the kept hook runs, never their payloads; `--json` adds the outstanding and failed totals.

The `acted` column says whether the hook had acted when the run failed: `start` (a
retry replays the tool's start), `""` or `cancel` (a retry runs the hook again), or
`resume` or `take` (it can only be discarded).

Example: `tai hooks runs list --status failed`

```console theme={null}
$ tai hooks runs list [OPTIONS]
```

| Option | Description |
| - | - |
| `--status` `&lt;str&gt;` | 'outstanding' (pending and running runs) or 'failed' (the failed ones). |
| `--limit` `&lt;int&gt;` | Page size. |
| `--cursor` `&lt;str&gt;` | The next\_cursor of a prior page. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

### `tai hooks runs retry`

Retry a failed hook run with the same id, and so the same idempotency key.

A run whose hook started its tool replays that start alone; any other runs its hook again.
A run whose hook committed a resume or a take is refused, and the refusal says why.

Example: `tai hooks runs retry RUN_ID`

```console theme={null}
$ tai hooks runs retry [OPTIONS] {ID}
```

| Argument | Description |
| - | - |
| `ID` | The failed hook run's id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai hooks set-verifier`

Bind a webhook verifier to a topic so its deliveries are signature-verified.

ADMIN-ONLY: a `hooks`-write role is fenced out of this door and reads a bare 403.

Binding also takes every trigger link on the topic OUT OF SERVICE until it is
removed — those doors answer a uniform 404 while the binding stands.

Example: `tai hooks set-verifier github --verifier github_hmac`

```console theme={null}
$ tai hooks set-verifier [OPTIONS] {topic}
```

| Argument | Description |
| - | - |
| `topic` | Hook topic. *(required)* |

| Option | Description |
| - | - |
| `--verifier` `&lt;str&gt;` | Registered webhook-verifier name. *(required)* |
| `--config` `&lt;str&gt;` | Verifier config as a JSON object. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai hooks trigger-links`

List trigger links.

Each record carries name, topic, execution key, door auth, expiry, and hash prefix; never a raw token.

Example: `tai hooks trigger-links`

```console theme={null}
$ tai hooks trigger-links [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai hooks verifiers`

List the registered webhook-verifier names (the bind catalog).

Example: `tai hooks verifiers`

```console theme={null}
$ tai hooks verifiers [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# CLI
Source: https://docs.tai42.ai/reference/cli/index

The tai command-line tool: one entrypoint, global flags, and config resolution.

`tai` is the single command-line entrypoint for operating a server from the
terminal. It groups every surface — tools, presets, agents, connectors, keys,
schedules, and more — under one command tree. The per-group pages in this
section render from the live command tree, so their usage and options never
drift from the code.

```console theme={null}
$ tai [OPTIONS] COMMAND [ARGS]...
```

Run `tai --help`, or `tai <command> --help`, for the same tree these pages
document.

## Command groups

> **[serve](/reference/cli/serve)**
>
> Boot a server locally.

> **[tools](/reference/cli/tools)**
>
> Inspect and manage registered tools.

> **[agents](/reference/cli/agents)**
>
> Inspect and manage agents.

> **[presets](/reference/cli/presets)**
>
> Manage versioned tool presets.

> **[connectors](/reference/cli/connectors)**
>
> Manage OAuth connectors.

> **[plugins](/reference/cli/plugins)**
>
> Browse the marketplace and install plugins.

> **[keys](/reference/cli/keys)**
>
> Mint and manage API keys.

> **[config](/reference/cli/config)**
>
> Inspect the resolved configuration.

> **[doctor](/reference/cli/doctor)**
>
> Diagnose the local environment.

## Global options

These flags apply to every command:

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. Pipe the JSON into other tools. |
| `--server URL` | The server base URL to talk to. |
| `--api-key-stdin` | Read the API key as one line from stdin, rather than prompting. |

> [!NOTE]
>
> There is no `--api-key VALUE` flag: a key on the command line leaks through
> `ps` and shell history. Supply the key through the environment, the config
> file, `--api-key-stdin`, or the interactive prompt.

## Server URL resolution

`tai` resolves the server it talks to in this order, first match wins:

**1. The --server flag**

An explicit `--server URL` on the command line.

**2. The TAI\_SERVER\_URL environment variable**

Set it to point a shell session at a server.

**3. The config file**

The `server_url` key in `config.toml`.

**4. The local default**

`http://127.0.0.1:8000` — the port is `tai42-cli`'s own default, which the
skeleton's `serve` settings import, so `tai serve` and this default always
agree.

## API-key resolution

The API key resolves in this order, first match wins:

**1. --api-key-stdin**

Read one line from stdin — the way to pass a key from a secret store.

**2. The TAI\_API\_KEY environment variable**

Set it for a shell session.

**3. The config file**

The `api_key` key in `config.toml`.

**4. An interactive prompt**

A hidden prompt, as a last resort.

## Config file

`tai` reads a TOML config file at `$XDG_CONFIG_HOME/tai/config.toml`, or
`~/.config/tai/config.toml` when `XDG_CONFIG_HOME` is unset. It recognizes two
keys:

```toml theme={null}
server_url = "https://your-server/"
api_key = "tai-..."
```

A malformed config file raises loudly rather than being ignored.

## Local vs remote commands

The command ships in two packages. `tai42-cli` provides the `tai` command itself
and the remote groups — thin clients over the HTTP API — so `pip install tai42-cli`
operates a running server from anywhere. The local commands are added by
`tai42-skeleton`, which contributes them to the same tree when it is installed
alongside.

Most commands call the server's [HTTP API](/reference/api) and so resolve a
server URL and an API key. A few run locally and never contact a server —
`tai serve` boots one, `tai openapi` emits the API spec offline, `tai version`
and `tai doctor` inspect the local environment, and `tai completion` installs
shell completion.


# tai interactions
Source: https://docs.tai42.ai/reference/cli/interactions

List, stream and answer pending interactions.

List, stream and answer pending interactions.

```console theme={null}
$ tai interactions [OPTIONS] COMMAND [ARGS]...
```

## `tai interactions answer`

Answer a pending interaction. The value is validated server-side.

Example: `tai interactions answer i_123 --answer '"yes"'`

```console theme={null}
$ tai interactions answer [OPTIONS] {interaction_id}
```

| Argument | Description |
| - | - |
| `interaction_id` | Interaction id. *(required)* |

| Option | Description |
| - | - |
| `--answer` `&lt;str&gt;` | The answer value as JSON (a string, bool, object, ...). *(required)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai interactions cancel`

Cancel a pending interaction — withdraw the ask without answering it.

The parked flow is never resumed and the interaction's thread is left intact; a
question that is already answered is a conflict and a gone/expired one is not found.

Example: `tai interactions cancel i_123`

```console theme={null}
$ tai interactions cancel [OPTIONS] {interaction_id}
```

| Argument | Description |
| - | - |
| `interaction_id` | Interaction id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai interactions list`

Print one page of pending interactions.

Example: `tai interactions list --page 1 --page-size 50`

```console theme={null}
$ tai interactions list [OPTIONS]
```

| Option | Description |
| - | - |
| `--page` `&lt;int&gt;` | Page number (1-based). |
| `--page-size` `&lt;int&gt;` | Items per page (capped at 200). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai interactions pending`

Print the parked (async) interactions awaiting an answer.

The operator-only audit a watchdog reads to spot asks nearing or past their expiry.

Example: `tai interactions pending --limit 100`

```console theme={null}
$ tai interactions pending [OPTIONS]
```

| Option | Description |
| - | - |
| `--limit` `&lt;int&gt;` | Max parked asks to return, 1..1000 (default 500). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai interactions stream`

Tail the interactions inbox live (add/answered/removed events).

Example: `tai interactions stream`

```console theme={null}
$ tai interactions stream [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai keys
Source: https://docs.tai42.ai/reference/cli/keys

Manage API keys and their access-control conditions.

Manage API keys and their access-control conditions.

```console theme={null}
$ tai keys [OPTIONS] COMMAND [ARGS]...
```

## `tai keys claim-link`

Mint a one-time claim link that carries a key you hold to another device.

The link's token rides the URL FRAGMENT of the deployment's login page and is
SINGLE-USE — the first exchange burns it. Prints the claim path and expiry; compose
the absolute URL (or a QR) from your own origin.

Example: `tai keys claim-link sk-abc123 --ttl 300`

```console theme={null}
$ tai keys claim-link [OPTIONS] [raw_key]
```

| Argument | Description |
| - | - |
| `raw_key` | The raw API key to share (omit to enter it at a hidden prompt so it never lands in shell history). *(optional)* |

| Option | Description |
| - | - |
| `--ttl` `&lt;int&gt;` | Link lifetime in seconds (capped by the server ceiling). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai keys create`

Provision an API key; the raw `sk-…` value is printed ONCE.

Example: `tai keys create --user alice --description 'CI key' --scope read`

```console theme={null}
$ tai keys create [OPTIONS]
```

| Option | Description |
| - | - |
| `--user` `&lt;str&gt;` | The key's user id. *(required)* |
| `--description` `&lt;str&gt;` | Human description (required identity field). *(required)* |
| `--for` `&lt;str&gt;` | The principal that owns the key (admin only); omitted = the caller's own principal. |
| `--scope` `&lt;str&gt;` | A scope to grant (repeatable). |
| `--condition` `&lt;str&gt;` | The authorization condition as a templated-text JSON object: inline jq under "content" OR a stored resource "id" (exactly one), plus optional render "kwargs". Example: '\{"content": ".method == "GET""}'. |
| `--condition-file` `&lt;str&gt;` | Read the condition templated-text JSON object from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --condition. |
| `--policy-data` `&lt;str&gt;` | Extra policy data as a JSON object. |
| `--policy-data-file` `&lt;str&gt;` | Read the policy data JSON object from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --policy-data. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai keys delete`

Revoke a key (immediate: the next request fails to auth).

Revoking also STOPS every hook and trigger link bound to this key as its
`execution_key` — their next fire is refused. Run `tai hooks list` and
`tai hooks trigger-links` first to see which records bind it.

Example: `tai keys delete alice`

```console theme={null}
$ tai keys delete [OPTIONS] {user}
```

| Argument | Description |
| - | - |
| `user` | The key's user id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai keys edit`

Partially edit a key's description/scopes/policy in place (no rotation).

Only the flags you pass are written; omitted fields are preserved. `--clear-condition`
sends the explicit reset (`condition: null`) that drops the key's gate, distinct from
omitting the flag entirely.

De-scoping this key (or its owner) also NARROWS what every hook and trigger link
bound to it as its `execution_key` may call at its next fire — see `tai hooks
list` for which records bind it.

Example: `tai keys edit alice --scope read --scope write`

```console theme={null}
$ tai keys edit [OPTIONS] {user}
```

| Argument | Description |
| - | - |
| `user` | The key's user id. *(required)* |

| Option | Description |
| - | - |
| `--description` `&lt;str&gt;` | New description. |
| `--scope` `&lt;str&gt;` | Replacement scope (repeatable); replaces the set. |
| `--condition` `&lt;str&gt;` | The authorization condition as a templated-text JSON object: inline jq under "content" OR a stored resource "id" (exactly one), plus optional render "kwargs". Example: '\{"content": ".method == "GET""}'. |
| `--condition-file` `&lt;str&gt;` | Read the condition templated-text JSON object from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --condition. |
| `--clear-condition` | Remove the key's condition gate (leave it unconditional). *(default: `False`)* |
| `--policy-data` `&lt;str&gt;` | Policy data JSON; '\{}' clears. |
| `--policy-data-file` `&lt;str&gt;` | Read the policy data JSON object from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --policy-data. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai keys list`

List every provisioned key's identity and policy (never key material).

Example: `tai keys list`

```console theme={null}
$ tai keys list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai keys policy-rollback`

Roll a user's enforced policy back to a prior version.

Example: `tai keys policy-rollback alice 2`

```console theme={null}
$ tai keys policy-rollback [OPTIONS] {user} {version}
```

| Argument | Description |
| - | - |
| `user` | The key's user id. *(required)* |
| `version` | Target policy version to enforce. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai keys policy-versions`

List a user's append-only policy version history.

Example: `tai keys policy-versions alice`

```console theme={null}
$ tai keys policy-versions [OPTIONS] {user}
```

| Argument | Description |
| - | - |
| `user` | The key's user id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai keys scopes`

Add and/or remove individual scopes on a key WITHOUT replacing the whole set.

At least one --add or --remove is required. This is the granular complement of
`tai keys edit --scope`, which replaces the entire scope set at once.

Example: `tai keys scopes alice --add write --remove read`

```console theme={null}
$ tai keys scopes [OPTIONS] {user}
```

| Argument | Description |
| - | - |
| `user` | The key's user id. *(required)* |

| Option | Description |
| - | - |
| `--add` `&lt;str&gt;` | A scope to add (repeatable). |
| `--remove` `&lt;str&gt;` | A scope to remove (repeatable). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai keys validate-condition`

Compile (and optionally sample-evaluate) a jq policy condition without saving.

Example: `tai keys validate-condition --condition '&#123;"content": ".method == \\"GET\\""&#125;'`

```console theme={null}
$ tai keys validate-condition [OPTIONS]
```

| Option | Description |
| - | - |
| `--condition` `&lt;str&gt;` | The authorization condition as a templated-text JSON object: inline jq under "content" OR a stored resource "id" (exactly one), plus optional render "kwargs". Example: '\{"content": ".method == "GET""}'. |
| `--condition-file` `&lt;str&gt;` | Read the condition templated-text JSON object from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --condition. |
| `--sample-context` `&lt;str&gt;` | A JqAuthContext-shaped sample to evaluate against, as JSON. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai manifest
Source: https://docs.tai42.ai/reference/cli/manifest

Inspect the server manifest.

Inspect the server manifest.

```console theme={null}
$ tai manifest [OPTIONS] COMMAND [ARGS]...
```

## `tai manifest agents-add`

Add agents config entries to the manifest and hot-reload.

The file is ONE entry object, a bare JSON array of entries, or an object
carrying an `"entries"` list. Without `--replace` an entry whose title
already exists is refused.

Example: `tai manifest agents-add --file entries.json`

```console theme={null}
$ tai manifest agents-add [OPTIONS]
```

| Option | Description |
| - | - |
| `--file` `&lt;file&gt;` | A JSON file with the agents entries to add. *(required)* |
| `--replace` | Replace entries whose title already exists (in place) instead of refusing. *(default: `False`)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai manifest agents-remove`

Remove one agents config entry by title and hot-reload.

Example: `tai manifest agents-remove my-entry`

```console theme={null}
$ tai manifest agents-remove [OPTIONS] {title}
```

| Argument | Description |
| - | - |
| `title` | Agents config entry title. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai manifest api-tools`

Add/remove names on the api\_tools include/exclude lists and hot-reload.

At least one of the four options is required.

Example: `tai manifest api-tools --include-add echo --exclude-remove echo`

```console theme={null}
$ tai manifest api-tools [OPTIONS]
```

| Option | Description |
| - | - |
| `--include-add` `&lt;str&gt;` | A name to add to the include list (repeatable). |
| `--include-remove` `&lt;str&gt;` | A name to remove from the include list (repeatable). |
| `--exclude-add` `&lt;str&gt;` | A name to add to the exclude list (repeatable). |
| `--exclude-remove` `&lt;str&gt;` | A name to remove from the exclude list (repeatable). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai manifest plugins`

List the installed studio plugins declared by the manifest.

Example: `tai manifest plugins`

```console theme={null}
$ tai manifest plugins [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai manifest replace`

Replace the WHOLE persisted manifest from a file and reload the fleet.

Posts the manifest TEXT verbatim — `!ENV` markers are left INTACT so the server
resolves them (the persist-through replace keeps the preserved view, never baking
a resolved secret to disk). The persisted change reaches the whole fleet.

Example: `tai manifest replace --file config/manifest.yml`

```console theme={null}
$ tai manifest replace [OPTIONS]
```

| Option | Description |
| - | - |
| `--file` `&lt;file&gt;` | A manifest.yml file to install. *(required)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai manifest show`

Show the live manifest's MCP section and user tools.

Example: `tai manifest show`

```console theme={null}
$ tai manifest show [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai manifest tools-add`

Add tools config entries to the manifest and hot-reload.

The file is ONE entry object, a bare JSON array of entries, or an object
carrying an `"entries"` list. Without `--replace` an entry whose title
already exists is refused.

Example: `tai manifest tools-add --file entries.json`

```console theme={null}
$ tai manifest tools-add [OPTIONS]
```

| Option | Description |
| - | - |
| `--file` `&lt;file&gt;` | A JSON file with the tools entries to add. *(required)* |
| `--replace` | Replace entries whose title already exists (in place) instead of refusing. *(default: `False`)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai manifest tools-remove`

Remove one tools config entry by title and hot-reload.

Example: `tai manifest tools-remove my-entry`

```console theme={null}
$ tai manifest tools-remove [OPTIONS] {title}
```

| Argument | Description |
| - | - |
| `title` | Tools config entry title. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai manifest validate`

Validate a manifest file against the Manifest model, OFFLINE (no server).

Loads the YAML (expanding `!ENV` tags exactly as the runtime read does) and
runs `Manifest.model_validate`. A broken manifest exits non-zero with the
model's validation error; a valid one prints a confirmation.

Example: `tai manifest validate config/manifest.yml`

```console theme={null}
$ tai manifest validate [OPTIONS] {file}
```

| Argument | Description |
| - | - |
| `file` | Path to a manifest.yml file. *(required)* |


# tai mcp
Source: https://docs.tai42.ai/reference/cli/mcp

Inspect and configure mounted MCP servers.

Inspect and configure mounted MCP servers.

```console theme={null}
$ tai mcp [OPTIONS] COMMAND [ARGS]...
```

## `tai mcp add`

Add MCP config entries to the manifest and hot-reload.

The file is ONE entry object, a bare JSON array of entries, or an object
carrying an `"entries"` list. Without `--replace` an entry whose title
already exists is refused.

Example: `tai mcp add --file entries.json`

```console theme={null}
$ tai mcp add [OPTIONS]
```

| Option | Description |
| - | - |
| `--file` `&lt;file&gt;` | A JSON file with the MCP entries to add. *(required)* |
| `--replace` | Replace entries whose title already exists (in place) instead of refusing. *(default: `False`)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai mcp deregister`

Detach a single MCP server's tools by title (the removal counterpart of reload).

Runtime-only detach; for persisted removal see `remove`.

Example: `tai mcp deregister my-server`

```console theme={null}
$ tai mcp deregister [OPTIONS] {title}
```

| Argument | Description |
| - | - |
| `title` | MCP server title. *(required)* |

| Option | Description |
| - | - |
| `--target` `&lt;str&gt;` | A worker to restrict the fan-out to (repeatable). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai mcp failed`

List the MCP servers skipped by the viability check (down/slow at boot or reload).

Example: `tai mcp failed`

```console theme={null}
$ tai mcp failed [OPTIONS]
```

| Option | Description |
| - | - |
| `--target` `&lt;str&gt;` | A worker to restrict the listing to (repeatable). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai mcp reload`

Reload a single MCP server by title.

Without `--target` the response is the single-worker status; with one or more
the confirmed fleet fan-out is awaited and per-worker results are returned.

Example: `tai mcp reload my-server`

```console theme={null}
$ tai mcp reload [OPTIONS] {title}
```

| Argument | Description |
| - | - |
| `title` | MCP server title. *(required)* |

| Option | Description |
| - | - |
| `--target` `&lt;str&gt;` | A worker to restrict the fan-out to (repeatable). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai mcp reload-failed`

Re-probe every failed MCP server and attach the ones now viable.

Example: `tai mcp reload-failed`

```console theme={null}
$ tai mcp reload-failed [OPTIONS]
```

| Option | Description |
| - | - |
| `--target` `&lt;str&gt;` | A worker to restrict the fan-out to (repeatable). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai mcp remove`

Remove one MCP config entry by title and hot-reload.

Persisted removal (see `deregister` for runtime-only detach).

Example: `tai mcp remove my-server`

```console theme={null}
$ tai mcp remove [OPTIONS] {title}
```

| Argument | Description |
| - | - |
| `title` | MCP server title. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai mcp schema`

Get the JSON schema for one MCP-config entry.

Example: `tai mcp schema`

```console theme={null}
$ tai mcp schema [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai mcp set`

Replace the MCP config section from a JSON file and hot-reload.

The file is the full replacement MCP list, either a bare JSON array or an
object carrying an `"mcp"` list.

Example: `tai mcp set --file mcp.json`

```console theme={null}
$ tai mcp set [OPTIONS]
```

| Option | Description |
| - | - |
| `--file` `&lt;file&gt;` | A JSON file with the full 'mcp' list. *(required)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai mcp status`

Snapshot the live MCP binding status.

Example: `tai mcp status`

```console theme={null}
$ tai mcp status [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai metrics
Source: https://docs.tai42.ai/reference/cli/metrics

Serve the Prometheus metrics endpoint.

Serve the Prometheus metrics endpoint.

```console theme={null}
$ tai metrics [OPTIONS]
```

| Option | Description |
| - | - |
| `--host` `TEXT` | Host to bind the server to |
| `--port` `INTEGER` | Port to run the server on |


# tai notifications
Source: https://docs.tai42.ai/reference/cli/notifications

Read and send internal notifications.

Read and send internal notifications.

```console theme={null}
$ tai notifications [OPTIONS] COMMAND [ARGS]...
```

## `tai notifications list`

List the internal notifications, newest-first.

Example: `tai notifications list`

```console theme={null}
$ tai notifications list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai notifications notify`

Send a human a one-way, fire-and-forget notification.

The rich-send forms are JSON strings validated into their contract models before the
request — a list of `MediaItem` for `--media`, a discriminated `Option` list
(reply/link) for `--options`, an `OptionSection` list for `--sections`, a
`ChannelTemplate` for `--template`, a `LocationElement` for `--location`, a
`MediaItem` for `--header`, a JSON object for `--schema`, a `FormData` for `--data`,
a `FormPage` list for `--pages` and a `Wording` for `--wording` — so a
mis-shaped value (including an unknown template/location/header/data/wording key, which
the contract would otherwise silently drop) raises loudly here. The contract's cross-field
rules (caps, non-blank, the options-XOR-sections choice surface, header/footer requiring a
choice surface, template exclusivity, the channel-deliverable form subset, the form data/pages
requiring a schema and matching its properties, and each `wording` member admitted only on the
surface that draws it) are enforced by the server.

Example: `tai notifications notify "Deploy finished" --channel telegram`

```console theme={null}
$ tai notifications notify [OPTIONS] {message}
```

| Argument | Description |
| - | - |
| `message` | The notification text shown to the human. *(required)* |

| Option | Description |
| - | - |
| `--channel` `&lt;str&gt;` | Named channel to send on; omit to record to the internal sink. |
| `--recipient` `&lt;str&gt;` | Optional per-call address (chat id, phone number, ...). |
| `--media` `&lt;str&gt;` | JSON array of display-media items sent WITH the message, e.g. '\[\{"kind":"image","url":"https\://…"}]'. |
| `--template` `&lt;str&gt;` | JSON object for an out-of-window template send — `name`, `language` and an optional channel-owned opaque `parameters` object (the declaring channel validates its shape), e.g. '\{"name":"status\_update","language":"en\_US","parameters":\{"body":\["A-42"]}}'. |
| `--options` `&lt;str&gt;` | JSON array of tappable options — each a reply (`&#123;"kind":"reply","text":"Yes","description":"…","id":"…"&#125;`, description/id optional) or a link (`&#123;"kind":"link","label":"Docs","url":"https://…"&#125;`), e.g. '\[\{"kind":"reply","text":"Yes"},\{"kind":"link","label":"Docs","url":"https\://x/d"}]'. |
| `--sections` `&lt;str&gt;` | JSON array of titled option sections (the sectioned alternative to --options), each `&#123;"title":"…","rows":[&#123;"kind":"reply","text":"…"&#125;]&#125;`, e.g. '\[\{"title":"Fruit","rows":\[\{"kind":"reply","text":"Apple"}]}]'. |
| `--location` `&lt;str&gt;` | JSON object for a shared map pin, `&#123;"latitude":51.5,"longitude":-0.12,"name":"…","address":"…"&#125;` (name/address optional). |
| `--header` `&lt;str&gt;` | JSON object for a single display-media header above an interactive message (requires --options or --sections), e.g. '\{"kind":"image","url":"https\://…"}'. |
| `--footer` `&lt;str&gt;` | Short trailing line under an interactive message (requires --options or --sections). |
| `--schema` `&lt;str&gt;` | JSON object holding an ask-less form's answer schema (channel-only; the message is the form's prompt), e.g. '\{"type":"object","properties":\{"name":\{"type":"string"}}}'. |
| `--data` `&lt;str&gt;` | JSON object of per-send form data over --schema — `values` prefills properties and `options` supplies a per-send choice list per property, e.g. '\{"values":\{"name":"Ada"},"options":\{"tier":\[\{"value":"gold"}]}}'. |
| `--pages` `&lt;str&gt;` | JSON array of stepped-form pages over --schema, each `&#123;"title":"…","fields":[…]&#125;` naming the properties on one step (every property appears exactly once), e.g. '\[\{"title":"You","fields":\["name"]}]'. |
| `--wording` `&lt;str&gt;` | JSON object of the notification's per-send platform-drawn texts, grouped by what each decorates — form (a form send's chrome), choice (a choice list's control words) and status (in-flight status copy), e.g. '\{"form":\{"open":"Fill in","submit":"Send"}}'. Each member is admitted only on the surface that draws it; an unknown key is rejected. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai obs
Source: https://docs.tai42.ai/reference/cli/obs

Query observability metrics.

Query observability metrics.

```console theme={null}
$ tai obs [OPTIONS] COMMAND [ARGS]...
```

## `tai obs metrics`

Query aggregate observability metrics over a time range.

Example: `tai obs metrics --from 7d --granularity day`

```console theme={null}
$ tai obs metrics [OPTIONS]
```

| Option | Description |
| - | - |
| `--from` `&lt;str&gt;` | Range start: an ISO instant or a relative token (30d). |
| `--to` `&lt;str&gt;` | Range end: an ISO instant or a relative token. |
| `--granularity` `&lt;str&gt;` | Series granularity: hour, day, or week. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai openapi
Source: https://docs.tai42.ai/reference/cli/openapi

Emit the OpenAPI 3.1 specification for the `/api/*` surface.

Emit the OpenAPI 3.1 specification for the `/api/*` surface.

Builds the spec offline from the app's registered routes — no database,
Redis, or live config services required. `--check` validates the spec
against the OpenAPI 3.1 schema (for CI / pre-deploy) and writes nothing.

```console theme={null}
$ tai openapi [OPTIONS]
```

| Option | Description |
| - | - |
| `--out` `PATH` | Write the spec to PATH instead of stdout. |
| `--check` | Validate the spec against the OpenAPI 3.1 schema and exit non-zero if invalid; write nothing. *(default: `False`)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai plugins
Source: https://docs.tai42.ai/reference/cli/plugins

Browse and install marketplace plugins.

Browse and install marketplace plugins.

```console theme={null}
$ tai plugins [OPTIONS] COMMAND [ARGS]...
```

## `tai plugins advisories`

Show the cached advisory snapshot for the installed plugins.

Example: `tai plugins advisories`

```console theme={null}
$ tai plugins advisories [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai plugins categories`

List the marketplace's controlled category vocabulary.

Example: `tai plugins categories`

```console theme={null}
$ tai plugins categories [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai plugins info`

Show one listing's detail and its published versions.

Example: `tai plugins info tai42/toolbox`

```console theme={null}
$ tai plugins info [OPTIONS] {ref}
```

| Argument | Description |
| - | - |
| `ref` | Plugin ref 'namespace/name'. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai plugins init`

Scaffold a descriptor-only plugin directory (yml, docs, licence, changelog).

`--kind connector` needs `--auth &#123;oauth,none&#125;`; `--kind mcp-server` takes no
`--auth`. The written tree parses as a plugin spec and its docs validate as-is;
edit the placeholders (`acme`, `example.invalid`, the icon) before publishing.

Example: `tai plugins init connector-acme --kind connector --auth oauth`

```console theme={null}
$ tai plugins init [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Plugin listing name (the 'name' half of namespace/name). *(required)* |

| Option | Description |
| - | - |
| `--kind` `&lt;str&gt;` | Item kind to scaffold: connector or mcp-server. *(required)* |
| `--auth` `&lt;str&gt;` | Connector auth mode (required for connector, forbidden for mcp-server). |
| `--dir` `&lt;path&gt;` | Target directory; defaults to ./NAME. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai plugins install`

Install a marketplace plugin by ref, optionally pinning a version.

`--mount` remaps a route-carrying item's base prefix; `--env KEY=VALUE` and
`--secret KEY` supply the install-time env the spec declares (an mcp entry's
`!ENV` markers or an oauth connector's client credentials, the secret
auto-marked); `--dry-run` previews the resolved routes, delivery, and required
env (exiting non-zero on any collision) without installing; and
`--accept-public-routes` is required when the plugin declares routes that
answer without authentication.

Before installing, the server's preview reports which required env is still
missing; an unresolved var not passed via `--env` fails the command before any
install is posted.

Example: `tai plugins install tai42/toolbox`

```console theme={null}
$ tai plugins install [OPTIONS] {ref}
```

| Argument | Description |
| - | - |
| `ref` | Plugin ref 'namespace/name'. *(required)* |

| Option | Description |
| - | - |
| `--version` `&lt;str&gt;` | Pin a specific version; omit for latest. |
| `--mount` `&lt;str&gt;` | Remap a route-carrying item's mount base as item=base (repeatable). |
| `--accept-public-routes` | Acknowledge routes that answer without authentication. *(default: `False`)* |
| `--dry-run` | Show the resolved routes, delivery, and required env without installing. *(default: `False`)* |
| `--env` `&lt;str&gt;` | Supply an install-time env value as KEY=VALUE (repeatable). |
| `--secret` `&lt;str&gt;` | Mark an env KEY secret (repeatable); the server auto-marks schema-known ones. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai plugins installed`

List installed marketplace plugins with compat verdicts and update availability.

Example: `tai plugins installed`

```console theme={null}
$ tai plugins installed [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai plugins kinds`

List the marketplace's controlled item-kind vocabulary.

Example: `tai plugins kinds`

```console theme={null}
$ tai plugins kinds [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai plugins schema`

Print the JSON Schema of a `tai-plugin.yml` (the `PluginSpec` model).

The canonical shape the marketplace validates against, including the `provides`
index; feed it to an editor or a validator.

Example: `tai plugins schema`

```console theme={null}
$ tai plugins schema [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai plugins search`

Search the marketplace registry, optionally filtered by facets.

Example: `tai plugins search uuid --kind tool`

```console theme={null}
$ tai plugins search [OPTIONS] [query]
```

| Argument | Description |
| - | - |
| `query` | Free-text search query; omit to browse all. *(optional)* |

| Option | Description |
| - | - |
| `--kind` `&lt;str&gt;` | Filter by provides kind (tool, agent, ...). |
| `--category` `&lt;str&gt;` | Filter by category. |
| `--tag` `&lt;str&gt;` | Filter by tag (repeatable). |
| `--namespace` `&lt;str&gt;` | Filter by publisher namespace. |
| `--tier` `&lt;str&gt;` | Filter by trust tier. |
| `--contract` `&lt;str&gt;` | Filter by compatible contract version. |
| `--sort` `&lt;str&gt;` | Sort order (downloads, updated, name). |
| `--page` `&lt;int&gt;` | Result page (1-based). |
| `--page-size` `&lt;int&gt;` | Results per page. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai plugins uninstall`

Uninstall a marketplace-installed plugin by ref.

Example: `tai plugins uninstall tai42/toolbox`

```console theme={null}
$ tai plugins uninstall [OPTIONS] {ref}
```

| Argument | Description |
| - | - |
| `ref` | Plugin ref 'namespace/name'. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai plugins update`

Update an installed plugin to a newer (or named) version.

`--env KEY=VALUE` and `--secret KEY` supply env a new version newly requires
(a fresh `!ENV` marker or connector credential); `--dry-run` previews the
target's delivery and required env. A required var still missing and not passed
via `--env` fails the command before any update is posted.

Example: `tai plugins update tai42/toolbox`

```console theme={null}
$ tai plugins update [OPTIONS] {ref}
```

| Argument | Description |
| - | - |
| `ref` | Plugin ref 'namespace/name'. *(required)* |

| Option | Description |
| - | - |
| `--version` `&lt;str&gt;` | Target version; omit for latest. |
| `--env` `&lt;str&gt;` | Supply an install-time env value as KEY=VALUE (repeatable). |
| `--secret` `&lt;str&gt;` | Mark an env KEY secret (repeatable); the server auto-marks schema-known ones. |
| `--dry-run` | Show the target's delivery and required env without updating. *(default: `False`)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai plugins upgrade`

Upgrade every installed plugin to its latest compatible version.

`--all` is required: the batch is deliberately explicit, and a single
plugin is upgraded with `tai plugins update REF` instead.

Example: `tai plugins upgrade --all`

```console theme={null}
$ tai plugins upgrade [OPTIONS]
```

| Option | Description |
| - | - |
| `--all` | Upgrade every installed plugin to its latest compatible version. *(default: `False`)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai presets
Source: https://docs.tai42.ai/reference/cli/presets

Manage preset tools and their versions.

Manage preset tools and their versions.

```console theme={null}
$ tai presets [OPTIONS] COMMAND [ARGS]...
```

## `tai presets create`

Create a versioned preset (or an authored agent, when the base tool is an agent).

Example: `tai presets create greet --base-tool echo --description 'Greet a user' --kwargs '&#123;"prefix":"hi"&#125;'`

```console theme={null}
$ tai presets create [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Preset name. *(required)* |

| Option | Description |
| - | - |
| `--base-tool` `&lt;str&gt;` | The registered non-preset tool the preset wraps. *(required)* |
| `--description` `&lt;str&gt;` | The preset's LLM-facing description (required, non-empty). *(required)* |
| `--kwargs` `&lt;str&gt;` | Baked fixed kwargs as a JSON object. A string value written '!ENV \$\{VAR}' is a secret reference the server resolves from that environment variable at run time, storing only the reference. |
| `--kwargs-file` `&lt;str&gt;` | Read the fixed kwargs JSON object from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --kwargs. |
| `--extensions` `&lt;str&gt;` | Extension combos as a JSON array of combos. Each combo is a non-empty array of elements, and an element is an extension name ('"chain"') or a \{"name","config"} object binding config to it (e.g. '\[\[\{"name":"output\_schema","config":\{"schema":\{"type":"object"}}}]]'). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai presets delete`

Delete a preset.

Example: `tai presets delete my_preset`

```console theme={null}
$ tai presets delete [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Preset name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai presets get`

Get a store-backed preset's record and active body.

Example: `tai presets get my_preset`

```console theme={null}
$ tai presets get [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Preset name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai presets get-version`

Get a specific preset version.

Example: `tai presets get-version my_preset 3`

```console theme={null}
$ tai presets get-version [OPTIONS] {name} {version}
```

| Argument | Description |
| - | - |
| `name` | Preset name. *(required)* |
| `version` | Version number. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai presets list`

List the store-backed (versioned) presets.

Example: `tai presets list`

```console theme={null}
$ tai presets list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai presets referees`

List the presets that reference this preset (a rename would strand them).

Example: `tai presets referees my_preset`

```console theme={null}
$ tai presets referees [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Preset name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai presets rename`

Rename a preset — its name is its live tool name, so the tool is rebound.

Example: `tai presets rename old_name new_name`

```console theme={null}
$ tai presets rename [OPTIONS] {name} {new_name}
```

| Argument | Description |
| - | - |
| `name` | Current preset name. *(required)* |
| `new_name` | New preset name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai presets rollback`

Roll a preset back to a prior version.

Example: `tai presets rollback my_preset 2`

```console theme={null}
$ tai presets rollback [OPTIONS] {name} {version}
```

| Argument | Description |
| - | - |
| `name` | Preset name. *(required)* |
| `version` | Target version to make active. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai presets save-version`

Save a new preset version.

Omitted fields carry forward; `--extensions '[]'` sends the explicit clear sentinel.

Example: `tai presets save-version my_preset --kwargs '&#123;"n":2&#125;'`

```console theme={null}
$ tai presets save-version [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Preset name. *(required)* |

| Option | Description |
| - | - |
| `--kwargs` `&lt;str&gt;` | New fixed kwargs (JSON object); omit to carry forward. A string value written '!ENV \$\{VAR}' is a secret reference the server resolves from that environment variable at run time, storing only the reference. |
| `--kwargs-file` `&lt;str&gt;` | Read the fixed kwargs JSON object from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --kwargs. |
| `--description` `&lt;str&gt;` | New description (non-empty); omit to carry the active one forward. |
| `--extensions` `&lt;str&gt;` | Extension combos as a JSON array of combos. Each combo is a non-empty array of elements, and an element is an extension name ('"chain"') or a \{"name","config"} object binding config to it (e.g. '\[\[\{"name":"output\_schema","config":\{"schema":\{"type":"object"}}}]]'). '\[]' clears them. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai presets set-version-tags`

Replace a preset version's tags (labels only — no rebind).

Zero tag arguments clears them to `[]`.

Example: `tai presets set-version-tags my_preset 2 stable reviewed`

```console theme={null}
$ tai presets set-version-tags [OPTIONS] {name} {version} [tags]...
```

| Argument | Description |
| - | - |
| `name` | Preset name. *(required)* |
| `version` | Version number. *(required)* |
| `tags...` | The tags to set; none clears them to \[]. *(optional)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai presets validate`

Dry-run a preset draft without writing anything.

Reports whether it would be accepted as a create (a new name) or a new version (an existing name).

Example: `tai presets validate greet --base-tool echo --description 'Greet' --kwargs '&#123;"prefix":"hi"&#125;'`

```console theme={null}
$ tai presets validate [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Preset name. *(required)* |

| Option | Description |
| - | - |
| `--base-tool` `&lt;str&gt;` | The base tool (required for a new preset). |
| `--kwargs` `&lt;str&gt;` | Baked fixed kwargs as a JSON object. A string value written '!ENV \$\{VAR}' is a secret reference the server resolves from that environment variable at run time, storing only the reference. |
| `--kwargs-file` `&lt;str&gt;` | Read the fixed kwargs JSON object from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --kwargs. |
| `--description` `&lt;str&gt;` | The preset's LLM-facing description. |
| `--extensions` `&lt;str&gt;` | Extension combos as a JSON array of combos. Each combo is a non-empty array of elements, and an element is an extension name ('"chain"') or a \{"name","config"} object binding config to it (e.g. '\[\[\{"name":"output\_schema","config":\{"schema":\{"type":"object"}}}]]'). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai presets versions`

List a preset's version history.

Example: `tai presets versions my_preset`

```console theme={null}
$ tai presets versions [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Preset name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai principals
Source: https://docs.tai42.ai/reference/cli/principals

Manage the deployment's principals.

Manage the deployment's principals.

```console theme={null}
$ tai principals [OPTIONS] COMMAND [ARGS]...
```

## `tai principals create`

Create a human or service principal under a role.

Example: `tai principals create --kind service --display-name 'CI runner' --role editor`

```console theme={null}
$ tai principals create [OPTIONS]
```

| Option | Description |
| - | - |
| `--kind` `&lt;human\|service&gt;` | The principal's kind. *(required)* |
| `--display-name` `&lt;str&gt;` | How the principal appears in listings. *(required)* |
| `--role` `&lt;str&gt;` | The role template the principal's keys inherit (see `tai roles`). *(required)* |
| `--user` `&lt;str&gt;` | The principal's id (omitted = server-minted). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai principals delete`

Delete a principal — REVOKES every key it owns and drops its policy.

Deletion is immediate and cannot be undone: each key the principal owns stops
authenticating on its next request. List the keys with `tai keys list` first.

Example: `tai principals delete usr-abc123`

```console theme={null}
$ tai principals delete [OPTIONS] {user}
```

| Argument | Description |
| - | - |
| `user` | The principal's id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai principals disable`

Disable a principal — its keys stop authenticating until it is re-enabled.

Example: `tai principals disable usr-abc123`

```console theme={null}
$ tai principals disable [OPTIONS] {user}
```

| Argument | Description |
| - | - |
| `user` | The principal's id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai principals enable`

Re-enable a disabled principal — its keys authenticate again.

Example: `tai principals enable usr-abc123`

```console theme={null}
$ tai principals enable [OPTIONS] {user}
```

| Argument | Description |
| - | - |
| `user` | The principal's id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai principals list`

List every principal with its kind, display name, and disabled state.

Example: `tai principals list`

```console theme={null}
$ tai principals list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai resources
Source: https://docs.tai42.ai/reference/cli/resources

Load stored resources by id.

Load stored resources by id.

```console theme={null}
$ tai resources [OPTIONS] COMMAND [ARGS]...
```

## `tai resources get`

Load a stored resource by id, optionally rendering it as a template.

Without `--render`/`--kw`/`--kwargs`/`--kwargs-file` the loaded content is
returned as-is. Any render var (or a bare `--render`) renders text as a Jinja template.

Example: `tai resources get prompts/greeting.md --kw name=Ada`

```console theme={null}
$ tai resources get [OPTIONS] {resource_id}
```

| Argument | Description |
| - | - |
| `resource_id` | Resource id (path) to load. *(required)* |

| Option | Description |
| - | - |
| `--render` | Render the resource as a Jinja template (with any --kw/--kwargs vars). *(default: `False`)* |
| `--kwargs` `&lt;str&gt;` | Render kwargs as a JSON object (implies --render). |
| `--kwargs-file` `&lt;str&gt;` | Read the render kwargs JSON object from a file, or from stdin when the path is '-' (implies --render), instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --kwargs; --kw pairs still override its keys. |
| `--kw` `&lt;str&gt;` | A key=value render kwarg (repeatable; implies --render). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai roles
Source: https://docs.tai42.ai/reference/cli/roles

Manage access-control roles.

Manage access-control roles.

```console theme={null}
$ tai roles [OPTIONS] COMMAND [ARGS]...
```

## `tai roles create`

Create a role over a base tier with a per-tag grant map.

Example: `tai roles create ops --base-tier editor --grant presets=write --grant hooks=read`

```console theme={null}
$ tai roles create [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | New role name. *(required)* |

| Option | Description |
| - | - |
| `--base-tier` `&lt;str&gt;` | Base tier: editor or viewer. *(required)* |
| `--grant` `&lt;str&gt;` | Repeatable tag=level (none/read/write). |
| `--description` `&lt;str&gt;` | Role description. *(default: \`)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai roles delete`

Delete a role (rejected while any principal still holds it).

Example: `tai roles delete ops`

```console theme={null}
$ tai roles delete [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Role name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai roles edit`

Edit a role's per-tag grant map (and optionally its description).

LIVE — every holder's reach changes on their next request.

Example: `tai roles edit ops --grant hooks=write`

```console theme={null}
$ tai roles edit [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Role name. *(required)* |

| Option | Description |
| - | - |
| `--grant` `&lt;str&gt;` | Repeatable tag=level (none/read/write). |
| `--description` `&lt;str&gt;` | New description. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai roles grants`

Set (upsert) and/or remove single tag grants on a role without replacing the whole map.

At least one `--set` or `--remove` is required. LIVE — every holder's reach changes on
their next request.

Example: `tai roles grants ops --set hooks=write --remove presets`

```console theme={null}
$ tai roles grants [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Role name. *(required)* |

| Option | Description |
| - | - |
| `--set` `&lt;str&gt;` | Repeatable tag=level (none/read/write) to set (upsert). |
| `--remove` `&lt;str&gt;` | Repeatable tag to remove. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai roles list`

List every role with its base tier, grant map, and allow\_all flag.

Example: `tai roles list`

```console theme={null}
$ tai roles list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai roles rollback`

Roll a role back to a prior version (LIVE — holders follow on their next request).

Example: `tai roles rollback ops 2`

```console theme={null}
$ tai roles rollback [OPTIONS] {name} {version}
```

| Argument | Description |
| - | - |
| `name` | Role name. *(required)* |
| `version` | Version number to roll back to. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai roles show`

Show one role's full definition (filtered from the roles listing).

Example: `tai roles show editor`

```console theme={null}
$ tai roles show [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Role name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai roles versions`

Show a role's version history and its who/when/before→after audit trail.

Example: `tai roles versions ops`

```console theme={null}
$ tai roles versions [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Role name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai runs
Source: https://docs.tai42.ai/reference/cli/runs

List and prune the platform runs index.

List and prune the platform runs index.

```console theme={null}
$ tai runs [OPTIONS] COMMAND [ARGS]...
```

## `tai runs list`

List platform runs, newest first, filtered by the given flags.

Each row carries `resumedInteractions` — the parked interaction ids the run
resumed or took across its dispatch span (empty when it resumed nothing).

Example: `tai runs list --preset assistant --outcome error`

```console theme={null}
$ tai runs list [OPTIONS]
```

| Option | Description |
| - | - |
| `--preset` `&lt;str&gt;` | Filter to one preset name. |
| `--version` `&lt;int&gt;` | Filter to one preset version. |
| `--user` `&lt;str&gt;` | Filter to one run user (attribution user identity). |
| `--session` `&lt;str&gt;` | Filter to one run session/thread (attribution session identity). |
| `--interaction` `&lt;str&gt;` | Filter to one park lifecycle by interaction id (the parked run and its resume). |
| `--outcome` `&lt;str&gt;` | Filter to one outcome: running, success, error, parked, or aborted. |
| `--from` `&lt;str&gt;` | Inclusive lower bound on the run start as an ISO-8601 instant. |
| `--to` `&lt;str&gt;` | Inclusive upper bound on the run start as an ISO-8601 instant. |
| `--page` `&lt;int&gt;` | Page number (1-based). |
| `--page-size` `&lt;int&gt;` | Rows per page. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai runs prune`

Delete runs-index rows older than the configured retention window.

A deployment-wide destructive purge (admin only), mirroring the checkpoint sweep.

Example: `tai runs prune`

```console theme={null}
$ tai runs prune [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai sandbox
Source: https://docs.tai42.ai/reference/cli/sandbox

Inspect the sandbox provider's identity and resolved policy.

Inspect the sandbox provider's identity and resolved policy.

```console theme={null}
$ tai sandbox [OPTIONS] COMMAND [ARGS]...
```

## `tai sandbox info`

Show the registered sandbox provider's identity and resolved policy (or the empty state).

Example: `tai sandbox info`

```console theme={null}
$ tai sandbox info [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai schedules
Source: https://docs.tai42.ai/reference/cli/schedules

Manage scheduled jobs.

Manage scheduled jobs.

```console theme={null}
$ tai schedules [OPTIONS] COMMAND [ARGS]...
```

## `tai schedules add`

Create a schedule that runs a tool on a cadence, or once now with no cadence.

The cadence is one of `--every` / `--cron` / `--cadence` (at most one); with none
the tool runs once now. The four door-contract jqs (`--start-expr` / `--cancel-expr` /
`--resume-expr` / `--extras-expr`) make the schedule a parkable-driving door; any of
them requires `--execution-key`.

Example: `tai schedules add report --cron '0 9 * * *'`

```console theme={null}
$ tai schedules add [OPTIONS] {tool_name}
```

| Argument | Description |
| - | - |
| `tool_name` | The tool to run on a schedule. *(required)* |

| Option | Description |
| - | - |
| `--tool-kwargs` `&lt;str&gt;` | Tool arguments as a JSON object. |
| `--tool-kwargs-file` `&lt;str&gt;` | Read the tool arguments JSON object from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --tool-kwargs; --tool-kw pairs still override its keys. |
| `--tool-kw` `&lt;str&gt;` | A key=value tool argument (repeatable). |
| `--every` `SECONDS` | Run every SECONDS (an interval cadence, > 0). |
| `--cron` `EXPR` | Run on a crontab EXPR (5 fields, or 6 with a leading seconds field). |
| `--cadence` `&lt;str&gt;` | The cadence as a JSON object, e.g. \{"kind": "interval", "every": 60}. |
| `--schedule-name` `NAME` | The schedule's name (needs a cadence). |
| `--execution-key` `&lt;str&gt;` | The api-key user id a contract-bearing recurring fire runs as (required with any contract jq). |
| `--start-expr` `&lt;str&gt;` | jq building the fired tool's kwargs over the tool arguments; null starts nothing. |
| `--cancel-expr` `&lt;str&gt;` | jq naming the parked interaction ids to cancel. |
| `--resume-expr` `&lt;str&gt;` | jq naming the parked interactions to resume or take. |
| `--extras-expr` `&lt;str&gt;` | jq building the extras mapping handed to the started target. |
| `--subject` `&lt;str&gt;` | The schedule-door state context as a JSON object the fire keys its writes on. |
| `--state-binding` `&lt;str&gt;` | The door-layer state binding as a JSON object. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai schedules delete`

Delete a schedule by name.

Example: `tai schedules delete report`

```console theme={null}
$ tai schedules delete [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Schedule name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai schedules list`

List the configured schedules (name, tool, cadence, enabled, next run).

Example: `tai schedules list`

```console theme={null}
$ tai schedules list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai schedules server-datetime`

Get the server's current date and time.

Example: `tai schedules server-datetime`

```console theme={null}
$ tai schedules server-datetime [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai scopes
Source: https://docs.tai42.ai/reference/cli/scopes

Manage access-control scopes.

Manage access-control scopes.

```console theme={null}
$ tai scopes [OPTIONS] COMMAND [ARGS]...
```

## `tai scopes add`

Map a URL to a scope (optionally with a dynamic match pattern).

Example: `tai scopes add read /api/tools`

```console theme={null}
$ tai scopes add [OPTIONS] {scope_id} {url}
```

| Argument | Description |
| - | - |
| `scope_id` | Scope id. *(required)* |
| `url` | URL to map into the scope. *(required)* |

| Option | Description |
| - | - |
| `--pattern` `&lt;str&gt;` | Optional dynamic match pattern. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai scopes delete`

Delete a scope.

Example: `tai scopes delete read`

```console theme={null}
$ tai scopes delete [OPTIONS] {scope_id}
```

| Argument | Description |
| - | - |
| `scope_id` | Scope id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai scopes list`

List every non-public route mapping as `&#123;url: scope_id&#125;`.

Example: `tai scopes list`

```console theme={null}
$ tai scopes list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai scopes public-list`

List every route pinned to the public marker.

Example: `tai scopes public-list`

```console theme={null}
$ tai scopes public-list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai scopes public-pin`

Pin a URL public (optionally with a dynamic match pattern).

The pin is for a route that does NOT declare itself public — an authed registered route
an operator chooses to open (e.g. `/metrics`), or a path a mounted app serves that the
registry does not describe. A route declared public at registration needs no pin, and a
pin never re-protects a declared-public route.

Example: `tai scopes public-pin /metrics`

```console theme={null}
$ tai scopes public-pin [OPTIONS] {url}
```

| Argument | Description |
| - | - |
| `url` | URL to pin public. *(required)* |

| Option | Description |
| - | - |
| `--pattern` `&lt;str&gt;` | Optional dynamic match pattern. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai scopes public-unpin`

Unpin a public URL.

Example: `tai scopes public-unpin /metrics`

```console theme={null}
$ tai scopes public-unpin [OPTIONS] {url}
```

| Argument | Description |
| - | - |
| `url` | URL to unpin. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai scopes remove-url`

Remove a URL from every scope that references it.

Example: `tai scopes remove-url /api/tools`

```console theme={null}
$ tai scopes remove-url [OPTIONS] {url}
```

| Argument | Description |
| - | - |
| `url` | URL to unmap from every scope. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai scopes routes`

List the app's HTTP routes with each route's scope mapping.

A `mapped` of `null` marks an unassigned route. Example: `tai scopes routes`

```console theme={null}
$ tai scopes routes [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai serve
Source: https://docs.tai42.ai/reference/cli/serve

Run the tai MCP server (FastMCP + Starlette), serving the Studio SPA too.

Run the tai MCP server (FastMCP + Starlette), serving the Studio SPA too.


Worker / transport combinations:

| transport | workers=1 | workers>1 |
| - | - | - |
| stdio | ok (no --stateless-http) | refused |
| sse | ok (no --stateless-http) | refused |
| http / streamable-http | ok (stateful default) | refused unless --stateless-http |


Worker-bus boot rules (set TAI\_BUS\_REDIS\_URL to enable the bus):

* with more than one worker, each worker refuses to boot without the bus —
  sibling workers would serve stale config after a reload with no channel to
  converge on;
* a non-file TAI\_CONFIG\_MODE is refused without the bus — an external config
  provider serves shared config and one instance cannot see its sibling count;
* a manifest that registers a task backend is refused without the bus — the
  backend-runtime and server processes must converge on reloads.

Store boot rules: with more than one worker, each worker refuses to boot while
the sub-MCP registration store is in-memory (set SUB\_MCP\_REDIS\_URL or
TAI\_DEFAULT\_REDIS\_URL), because a sub-MCP app registered through one worker would
not be served by its siblings, and while the hooks registry is in-memory (set
HOOKS\_REDIS\_URL or TAI\_DEFAULT\_REDIS\_URL), because a hook registered through one
worker would not run for the events its siblings accept. The workers check these
and the workers bus rule after the stored env is applied, so a bus or store URL
kept only in the config-dir .env or an external provider counts; a config reload
and a config write that would leave a multi-worker server without the bus or with
a store in-memory are refused the same way. A manifest that registers a task
backend is refused over an in-memory hooks registry at any worker count,
because the backend process matches the events it raises against its own
registry.

The worker count reaches these rules only through this CLI: an external process
manager driving the ASGI factory with its own --workers counts each process as
one worker for the workers bus and store rules, so set TAI\_BUS\_REDIS\_URL,
SUB\_MCP\_REDIS\_URL and HOOKS\_REDIS\_URL in any multi-process deployment.

```console theme={null}
$ tai serve [OPTIONS] [EXTRA_ARGS]...
```

| Argument | Description |
| - | - |
| `[EXTRA_ARGS]...` | *(optional)* |

| Option | Description |
| - | - |
| `--manifest-path` `TEXT` | Path to a YAML manifest file. |
| `-t` / `--transport` `[stdio\|http\|sse\|streamable-http]` | Transport mechanism. |
| `--host` `TEXT` | Host to bind the server to. |
| `--port` `INTEGER` | Port number to bind the server to. |
| `--uds` `TEXT` | Unix Domain Socket path. |
| `-w` / `--workers` `INTEGER` | Number of worker processes. More than one requires the worker bus (set TAI\_BUS\_REDIS\_URL) and shared sub-MCP and hooks stores (set SUB\_MCP\_REDIS\_URL and HOOKS\_REDIS\_URL, or TAI\_DEFAULT\_REDIS\_URL for all three; each worker checks them at boot, after the stored env is applied). *(default: `1`)* |
| `--stateless-http` / `--no-stateless-http` | Run an http/streamable-http transport in fastmcp's stateless mode, which lifts the single-worker restriction for those transports. Refused with 'sse'/'stdio'. *(default: `False`)* |


# tai setup
Source: https://docs.tai42.ai/reference/cli/setup

Initialize a fresh deployment: create the owner principal and mint its first key.

Initialize a fresh deployment: create the owner principal and mint its first key.

```console theme={null}
$ tai setup [OPTIONS] COMMAND [ARGS]...
```

| Option | Description |
| - | - |
| `--display-name` `&lt;str&gt;` | The owner principal's display name (required to initialize). |
| `--token` `&lt;str&gt;` | The setup token, or '-' to read it from stdin. The server auto-generates one and prints it in its startup log unless you set TAI\_SETUP\_TOKEN yourself, or the door is unavailable and mints none — access control off, no key-minting identity provider, or the access-control Redis unset (those three are also the 501 the door answers). Falls back to TAI\_SETUP\_TOKEN, then an interactive prompt. |
| `--user` `&lt;str&gt;` | The owner principal's id (omitted = server-minted). |
| `--key-user` `&lt;str&gt;` | The owner key's id (omitted = server-minted). |
| `--key-description` `&lt;str&gt;` | The owner key's description. *(default: `owner key`)* |
| `--password` `&lt;str&gt;` | Set the owner's password now (needs --email). |
| `--password-file` `&lt;str&gt;` | Read the owner's password from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). |
| `--invite` | Attach the owner's login via a one-time invite link instead of a password. *(default: `False`)* |
| `--no-login` | Keys-only: create the owner and its key, attach no login. *(default: `False`)* |
| `--email` `&lt;str&gt;` | The owner's email (required with --password/--invite). |
| `--recover` | Re-mint the owner's key when the deployment is initialized but no owner key can authenticate (host-side: reads the deployment's manifest and stores; needs the setup token). *(default: `False`)* |
| `--manifest-path` `&lt;str&gt;` | With --recover: the deployment's manifest (default: TAI\_MANIFEST\_PATH). |


# tai state-templates
Source: https://docs.tai42.ai/reference/cli/state-templates

Manage platform state-template documents.

Manage platform state-template documents.

```console theme={null}
$ tai state-templates [OPTIONS] COMMAND [ARGS]...
```

## `tai state-templates delete`

Delete a state-template document (refused while it is attached).

```console theme={null}
$ tai state-templates delete [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The template name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai state-templates get`

Show one state-template document.

```console theme={null}
$ tai state-templates get [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The template name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai state-templates list`

List every platform state-template document.

```console theme={null}
$ tai state-templates list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai state-templates put`

Create or replace a state-template document.

```console theme={null}
$ tai state-templates put [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The template name. *(required)* |

| Option | Description |
| - | - |
| `--data` `&lt;str&gt;` | The template document JSON. |
| `--file` `&lt;path&gt;` | A file holding the template document JSON. |
| `--replace` | Overwrite an existing template of this name. *(default: `False`)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai states
Source: https://docs.tai42.ai/reference/cli/states

Manage the subject-keyed state store.

Manage the subject-keyed state store.

```console theme={null}
$ tai states [OPTIONS] COMMAND [ARGS]...
```

## `tai states apply`

Apply an ordered op batch to a subject's document.

```console theme={null}
$ tai states apply [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--target-kind` `&lt;str&gt;` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `&lt;str&gt;` | The subject's conversation-target name. *(required)* |
| `--kind` `&lt;str&gt;` | The subject kind (e.g. person, thread). *(required)* |
| `--key` `&lt;str&gt;` | The subject key within its kind. *(required)* |
| `--data` `&lt;str&gt;` | A JSON array of ops (or \{ops, op\_id}). |
| `--file` `&lt;path&gt;` | A file holding the ops JSON. |
| `--op-id` `&lt;str&gt;` | An idempotency key for the batch. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states attach`

Attach a template on a state at a path with its parameters and declarations.

```console theme={null}
$ tai states attach [OPTIONS] {name} {template}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |
| `template` | The template name. *(required)* |

| Option | Description |
| - | - |
| `--data` `&lt;str&gt;` | The attach body JSON (path/parameters/declarations). |
| `--file` `&lt;path&gt;` | A file holding the attach body JSON. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states attachments`

List the templates attached on a state.

```console theme={null}
$ tai states attachments [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states check`

Page a state's stored records that do not fit its current effective schema.

```console theme={null}
$ tai states check [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--kind` `&lt;str&gt;` | Restrict to one subject kind. |
| `--limit` `&lt;int&gt;` | Page size. |
| `--cursor` `&lt;str&gt;` | A keyset cursor from a prior page. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states consumers`

List everything that binds a state — flows, hooks, schedules, agents.

```console theme={null}
$ tai states consumers [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states delete`

Delete a state with its records, attachments and aliases.

```console theme={null}
$ tai states delete [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states detach`

Detach a template from a state.

```console theme={null}
$ tai states detach [OPTIONS] {name} {template}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |
| `template` | The template name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states erase`

Erase a subject's record.

```console theme={null}
$ tai states erase [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--target-kind` `&lt;str&gt;` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `&lt;str&gt;` | The subject's conversation-target name. *(required)* |
| `--kind` `&lt;str&gt;` | The subject kind (e.g. person, thread). *(required)* |
| `--key` `&lt;str&gt;` | The subject key within its kind. *(required)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states fold`

Fold this subject's record into another canonical subject.

```console theme={null}
$ tai states fold [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--target-kind` `&lt;str&gt;` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `&lt;str&gt;` | The subject's conversation-target name. *(required)* |
| `--kind` `&lt;str&gt;` | The subject kind (e.g. person, thread). *(required)* |
| `--key` `&lt;str&gt;` | The subject key within its kind. *(required)* |
| `--into` `&lt;str&gt;` | The canonical subject JSON \{target\_kind,target\_name,kind,key}. *(required)* |
| `--mode` `&lt;str&gt;` | The fold mode. *(required)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states get`

Show a state's declaration, effective schema, attachments and regimes.

```console theme={null}
$ tai states get [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states get-attachment`

Read one template's attachment on a state (404 when it is not attached).

```console theme={null}
$ tai states get-attachment [OPTIONS] {name} {template}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |
| `template` | The template name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states list`

List every declared state.

```console theme={null}
$ tai states list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states merge`

Shallow-merge a patch into a subject's document.

```console theme={null}
$ tai states merge [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--target-kind` `&lt;str&gt;` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `&lt;str&gt;` | The subject's conversation-target name. *(required)* |
| `--kind` `&lt;str&gt;` | The subject kind (e.g. person, thread). *(required)* |
| `--key` `&lt;str&gt;` | The subject key within its kind. *(required)* |
| `--data` `&lt;str&gt;` | The patch JSON. |
| `--file` `&lt;path&gt;` | A file holding the patch JSON. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states pending-saves`

List, retry or discard pending state saves.

```console theme={null}
$ tai states pending-saves [OPTIONS] COMMAND [ARGS]...
```

### `tai states pending-saves discard`

Discard a failed pending save for good, releasing its subjects.

```console theme={null}
$ tai states pending-saves discard [OPTIONS] {ID}
```

| Argument | Description |
| - | - |
| `ID` | The failed pending save's id. *(required)* |

| Option | Description |
| - | - |
| `--yes` | Confirm: its writes and calls are never applied. *(default: `False`)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

### `tai states pending-saves list`

List the outstanding pending state saves, newest first.

```console theme={null}
$ tai states pending-saves list [OPTIONS]
```

| Option | Description |
| - | - |
| `--status` `&lt;str&gt;` | 'outstanding' (every save) or 'failed' (the failed ones). |
| `--limit` `&lt;int&gt;` | Page size. |
| `--cursor` `&lt;str&gt;` | A keyset cursor from a prior page. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

### `tai states pending-saves retry`

Retry a failed pending save: requeue it and apply its records now.

```console theme={null}
$ tai states pending-saves retry [OPTIONS] {ID}
```

| Argument | Description |
| - | - |
| `ID` | The failed pending save's id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states prune`

Prune every record past its state's retention horizon.

```console theme={null}
$ tai states prune [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states put`

Create or re-declare a state from a declaration document.

```console theme={null}
$ tai states put [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--data` `&lt;str&gt;` | The declaration JSON object. |
| `--file` `&lt;path&gt;` | A file holding the declaration JSON. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states read`

Read a subject's record (null when none exists).

```console theme={null}
$ tai states read [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--target-kind` `&lt;str&gt;` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `&lt;str&gt;` | The subject's conversation-target name. *(required)* |
| `--kind` `&lt;str&gt;` | The subject kind (e.g. person, thread). *(required)* |
| `--key` `&lt;str&gt;` | The subject key within its kind. *(required)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states replace`

Replace a subject's whole document.

```console theme={null}
$ tai states replace [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--target-kind` `&lt;str&gt;` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `&lt;str&gt;` | The subject's conversation-target name. *(required)* |
| `--kind` `&lt;str&gt;` | The subject kind (e.g. person, thread). *(required)* |
| `--key` `&lt;str&gt;` | The subject key within its kind. *(required)* |
| `--data` `&lt;str&gt;` | The document JSON. |
| `--file` `&lt;path&gt;` | A file holding the document JSON. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states search`

Search a state's records by document containment.

```console theme={null}
$ tai states search [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--filters` `&lt;str&gt;` | A JSON object the record document must contain. *(required)* |
| `--limit` `&lt;int&gt;` | Page size. |
| `--cursor` `&lt;str&gt;` | A keyset cursor from a prior page. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states stats`

Show a state's record counts (total and per subject kind).

```console theme={null}
$ tai states stats [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states subjects`

Page the subjects holding a record for a state.

```console theme={null}
$ tai states subjects [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--kind` `&lt;str&gt;` | Restrict to one subject kind. |
| `--limit` `&lt;int&gt;` | Page size. |
| `--cursor` `&lt;str&gt;` | A keyset cursor from a prior page. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states template-jq`

Evaluate/apply a state's template\_jq programs.

```console theme={null}
$ tai states template-jq [OPTIONS] COMMAND [ARGS]...
```

### `tai states template-jq apply`

Apply an update-purpose template\_jq program to a subject's record.

```console theme={null}
$ tai states template-jq apply [OPTIONS] {name} {program}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |
| `program` | The template\_jq program name (or \<template>.\<name>). *(required)* |

| Option | Description |
| - | - |
| `--target-kind` `&lt;str&gt;` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `&lt;str&gt;` | The subject's conversation-target name. *(required)* |
| `--kind` `&lt;str&gt;` | The subject kind (e.g. person, thread). *(required)* |
| `--key` `&lt;str&gt;` | The subject key within its kind. *(required)* |
| `--input` `&lt;str&gt;` | The program's input as JSON, or @\<file> to read it from a file. |
| `--op-id` `&lt;str&gt;` | An idempotency key for the apply. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

### `tai states template-jq eval`

Evaluate an input-purpose template\_jq program for a subject.

```console theme={null}
$ tai states template-jq eval [OPTIONS] {name} {program}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |
| `program` | The template\_jq program name (or \<template>.\<name>). *(required)* |

| Option | Description |
| - | - |
| `--target-kind` `&lt;str&gt;` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `&lt;str&gt;` | The subject's conversation-target name. *(required)* |
| `--kind` `&lt;str&gt;` | The subject kind (e.g. person, thread). *(required)* |
| `--key` `&lt;str&gt;` | The subject key within its kind. *(required)* |
| `--param` `&lt;str&gt;` | An input-program parameter as key=\<json> (repeatable). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states update-attachment`

Replace an attachment's static declaration values, with optional reconcile options.

```console theme={null}
$ tai states update-attachment [OPTIONS] {name} {template}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |
| `template` | The template name. *(required)* |

| Option | Description |
| - | - |
| `--declarations` `&lt;str&gt;` | The attachment declaration values JSON object. *(required)* |
| `--options` `&lt;str&gt;` | The reconcile options JSON object passed to attach reconcilers. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states validate`

Check a candidate document against a state's effective schema without storing it.

```console theme={null}
$ tai states validate [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--data` `&lt;str&gt;` | The candidate document JSON. |
| `--file` `&lt;path&gt;` | A file holding the candidate document JSON. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai states writes`

Page a subject's write audit trail.

```console theme={null}
$ tai states writes [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | The state name. *(required)* |

| Option | Description |
| - | - |
| `--target-kind` `&lt;str&gt;` | The subject's conversation-target kind (agent/tool). *(required)* |
| `--target-name` `&lt;str&gt;` | The subject's conversation-target name. *(required)* |
| `--kind` `&lt;str&gt;` | The subject kind (e.g. person, thread). *(required)* |
| `--key` `&lt;str&gt;` | The subject key within its kind. *(required)* |
| `--limit` `&lt;int&gt;` | Page size. |
| `--cursor` `&lt;str&gt;` | A keyset cursor from a prior page. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai storage
Source: https://docs.tai42.ai/reference/cli/storage

Inspect and manage the storage provider's resources.

Inspect and manage the storage provider's resources.

```console theme={null}
$ tai storage [OPTIONS] COMMAND [ARGS]...
```

## `tai storage delete`

Delete a storage resource.

Example: `tai storage delete notes/todo.txt`

```console theme={null}
$ tai storage delete [OPTIONS] {resource_id}
```

| Argument | Description |
| - | - |
| `resource_id` | Resource id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai storage delete-dir`

Delete a storage directory subtree.

Example: `tai storage delete-dir notes`

```console theme={null}
$ tai storage delete-dir [OPTIONS] {dir_path}
```

| Argument | Description |
| - | - |
| `dir_path` | Directory path. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai storage download`

Download a resource's raw content to stdout.

Example: `tai storage download notes/todo.txt`

```console theme={null}
$ tai storage download [OPTIONS] {resource_id}
```

| Argument | Description |
| - | - |
| `resource_id` | Resource id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai storage info`

Show the registered storage provider's identity (or the empty state).

Example: `tai storage info`

```console theme={null}
$ tai storage info [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai storage list`

List the storage resource ids.

Example: `tai storage list`

```console theme={null}
$ tai storage list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai storage stat`

Show a resource's inferred content type.

Example: `tai storage stat images/logo.png`

```console theme={null}
$ tai storage stat [OPTIONS] {resource_id}
```

| Argument | Description |
| - | - |
| `resource_id` | Resource id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai storage upload`

Upload a resource, overwriting any existing id.

Provide exactly one of `--text`, `--base64`, or `--file` (a path, or `-` to read the raw bytes from stdin).

Example: `tai storage upload notes/todo.txt --text 'buy milk'`

```console theme={null}
$ tai storage upload [OPTIONS] {resource_id}
```

| Argument | Description |
| - | - |
| `resource_id` | Resource id. *(required)* |

| Option | Description |
| - | - |
| `--text` `&lt;str&gt;` | Store this text verbatim. |
| `--base64` `&lt;str&gt;` | Store these base64-encoded bytes. |
| `--file` `&lt;str&gt;` | Store the raw bytes read from this file path, or from stdin when the path is '-', keeping secret content off the command line (a value on argv leaks via ps and shell history). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai sub-mcp
Source: https://docs.tai42.ai/reference/cli/sub-mcp

Register and inspect sub-MCP apps.

Register and inspect sub-MCP apps.

```console theme={null}
$ tai sub-mcp [OPTIONS] COMMAND [ARGS]...
```

## `tai sub-mcp delete`

Unregister a sub-MCP app.

Example: `tai sub-mcp delete utilities`

```console theme={null}
$ tai sub-mcp delete [OPTIONS] {slug}
```

| Argument | Description |
| - | - |
| `slug` | Sub-MCP app slug. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai sub-mcp list`

List the registered sub-MCP apps and their tools.

Example: `tai sub-mcp list`

```console theme={null}
$ tai sub-mcp list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai sub-mcp register`

Register (or reload) a sub-MCP app exposing the named tools under a slug.

Example: `tai sub-mcp register utilities --tool convert --tool lookup`

```console theme={null}
$ tai sub-mcp register [OPTIONS] {slug}
```

| Argument | Description |
| - | - |
| `slug` | Slug to mount the sub-MCP app under. *(required)* |

| Option | Description |
| - | - |
| `--tool` `&lt;str&gt;` | A tool name to expose (repeatable). *(required)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai system
Source: https://docs.tai42.ai/reference/cli/system

Inspect the server's own runtime surface.

Inspect the server's own runtime surface.

```console theme={null}
$ tai system [OPTIONS] COMMAND [ARGS]...
```

## `tai system kinds`

List every pluggable kind's live state (active / default / off).

Example: `tai system kinds`

```console theme={null}
$ tai system kinds [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai templates
Source: https://docs.tai42.ai/reference/cli/templates

Manage prompt and resource templates.

Manage prompt and resource templates.

```console theme={null}
$ tai templates [OPTIONS] COMMAND [ARGS]...
```

## `tai templates clear-cache`

Clear the template render cache.

Example: `tai templates clear-cache`

```console theme={null}
$ tai templates clear-cache [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai templates delete`

Delete a template.

Example: `tai templates delete prompts/greeting.md`

```console theme={null}
$ tai templates delete [OPTIONS] {path}
```

| Argument | Description |
| - | - |
| `path` | Template key to delete. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai templates delete-dir`

Delete every template under a directory.

A directory that matches no templates is a loud 404 (unlike `delete`, which
is idempotent for an absent single key).

Example: `tai templates delete-dir prompts/archive`

```console theme={null}
$ tai templates delete-dir [OPTIONS] {path}
```

| Argument | Description |
| - | - |
| `path` | Template directory to delete. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai templates get`

Fetch a template's content and its input schema.

Example: `tai templates get prompts/greeting.md`

```console theme={null}
$ tai templates get [OPTIONS] {template_id}
```

| Argument | Description |
| - | - |
| `template_id` | Template id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai templates list`

List the available templates.

Example: `tai templates list`

```console theme={null}
$ tai templates list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai templates render`

Render a templated text by id or inline content with kwargs.

Example: `tai templates render --text '&#123;"id": "prompts/greeting.md", "kwargs": &#123;"name": "Ada"&#125;&#125;'`

```console theme={null}
$ tai templates render [OPTIONS]
```

| Option | Description |
| - | - |
| `--text` `&lt;str&gt;` | The templated text to render as a JSON object: inline Jinja under "content" OR a stored resource id under "id" (exactly one), plus any render parameters under "kwargs". |
| `--text-file` `&lt;str&gt;` | Read the templated-text JSON object from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --text. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai templates upload`

Upload (create or overwrite) a template from a local file.

Example: `tai templates upload prompts/greeting.md --file greeting.md`

```console theme={null}
$ tai templates upload [OPTIONS] {path}
```

| Argument | Description |
| - | - |
| `path` | Template key to write. *(required)* |

| Option | Description |
| - | - |
| `--file` `&lt;file&gt;` | Local file whose content to upload. *(required)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai tool-meta
Source: https://docs.tai42.ai/reference/cli/tool-meta

Manage the tool-metadata overlay (folders, display names, tags, visibility).

Manage the tool-metadata overlay (folders, display names, tags, visibility).

```console theme={null}
$ tai tool-meta [OPTIONS] COMMAND [ARGS]...
```

## `tai tool-meta delete`

Delete a tool's whole overlay row (idempotent).

Example: `tai tool-meta delete web_search`

```console theme={null}
$ tai tool-meta delete [OPTIONS] {tool_name}
```

| Argument | Description |
| - | - |
| `tool_name` | The tool whose overlay row to drop. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tool-meta folder-create`

Create a folder (root, or under `--parent`).

Example: `tai tool-meta folder-create Research`

```console theme={null}
$ tai tool-meta folder-create [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Folder name. *(required)* |

| Option | Description |
| - | - |
| `--parent` `&lt;str&gt;` | Parent folder id; omit for a root folder. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tool-meta folder-delete`

Delete an empty folder.

Example: `tai tool-meta folder-delete &lt;id&gt;`

```console theme={null}
$ tai tool-meta folder-delete [OPTIONS] {folder_id}
```

| Argument | Description |
| - | - |
| `folder_id` | Folder id (must be empty). *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tool-meta folder-move`

Re-parent a folder (omit `--parent` to move it to the root).

Example: `tai tool-meta folder-move &lt;id&gt; --parent &lt;parent-id&gt;`

```console theme={null}
$ tai tool-meta folder-move [OPTIONS] {folder_id}
```

| Argument | Description |
| - | - |
| `folder_id` | Folder id. *(required)* |

| Option | Description |
| - | - |
| `--parent` `&lt;str&gt;` | New parent folder id; omit to move to the root. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tool-meta folder-rename`

Rename a folder.

Example: `tai tool-meta folder-rename &lt;id&gt; Archive`

```console theme={null}
$ tai tool-meta folder-rename [OPTIONS] {folder_id} {name}
```

| Argument | Description |
| - | - |
| `folder_id` | Folder id. *(required)* |
| `name` | New folder name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tool-meta list`

Show the whole overlay — every folder and every per-tool row.

Example: `tai tool-meta list`

```console theme={null}
$ tai tool-meta list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tool-meta set`

Merge-patch a tool's overlay.

Only the flags you pass are sent; omit a field to leave it unchanged.

Example: `tai tool-meta set web_search --display-name 'Web Search' --tag research`

```console theme={null}
$ tai tool-meta set [OPTIONS] {tool_name}
```

| Argument | Description |
| - | - |
| `tool_name` | The tool whose overlay to edit. *(required)* |

| Option | Description |
| - | - |
| `--display-name` `&lt;str&gt;` | Set the display label (non-empty). |
| `--clear-display-name` | Clear the display label (defer to the tool name). *(default: `False`)* |
| `--folder` `&lt;str&gt;` | Place the tool in this folder id. |
| `--clear-folder` | Remove the tool from its folder. *(default: `False`)* |
| `--tag` `&lt;str&gt;` | A user tag (repeatable); replaces the whole set when given. |
| `--clear-tags` | Clear all user tags (send an empty set). *(default: `False`)* |
| `--visibility` `&lt;str&gt;` | Visibility override: default (defer) \| shown \| hidden. |
| `--badge` `&lt;str&gt;` | A capability badge (repeatable); replaces the whole set when given. |
| `--clear-badges` | Clear all capability badges (send an empty set). *(default: `False`)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai tools
Source: https://docs.tai42.ai/reference/cli/tools

Inspect and run registered tools.

Inspect and run registered tools.

```console theme={null}
$ tai tools [OPTIONS] COMMAND [ARGS]...
```

## `tai tools apply`

Set a tool's full list of extension combos (lossless multi-combo write).

Each `--combo` is one combo, written as a JSON array of extension elements;
repeat it to author several combos at once. An element is a bare extension
name or a `&#123;"name", "config"&#125;` object binding author config, so per-element
config (e.g. an `output_schema` combo's schema) round-trips losslessly.
Passing no `--combo` clears every combo.

Example: `tai tools apply my_tool --combo '["chain","batch"]' --combo '["chain"]'`

```console theme={null}
$ tai tools apply [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Tool name. *(required)* |

| Option | Description |
| - | - |
| `--combo` `&lt;str&gt;` | One extension combo as a JSON array of elements (repeatable). Each element is an extension name ('"chain"') or a \{"name","config"} object binding config to it (e.g. '\[\{"name":"output\_schema","config":\{"schema":\{"type":"object"}}}]'). Passing no --combo clears the tool's extensions. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tools extensions`

Show a tool's applied extension combos and the available catalog.

Example: `tai tools extensions my_tool`

```console theme={null}
$ tai tools extensions [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Tool name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tools extensions-add`

Attach one or more extension combos to a tool, leaving its others in place.

Each `--combo` is one combo to append; repeat it to add several. Adding a
combo the tool already carries is refused by the server (400).

Example: `tai tools extensions-add my_tool --combo '["chain","batch"]'`

```console theme={null}
$ tai tools extensions-add [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Tool name. *(required)* |

| Option | Description |
| - | - |
| `--combo` `&lt;str&gt;` | One extension combo as a JSON array of elements (repeatable). Each element is an extension name ('"chain"') or a \{"name","config"} object binding config to it (e.g. '\[\{"name":"output\_schema","config":\{"schema":\{"type":"object"}}}]'). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tools extensions-remove`

Detach one or more extension combos from a tool, leaving its others in place.

Each `--combo` is one combo to drop; repeat it to remove several. Removing a
combo the tool does not carry is refused by the server (404).

Example: `tai tools extensions-remove my_tool --combo '["chain","batch"]'`

```console theme={null}
$ tai tools extensions-remove [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Tool name. *(required)* |

| Option | Description |
| - | - |
| `--combo` `&lt;str&gt;` | One extension combo as a JSON array of elements (repeatable). Each element is an extension name ('"chain"') or a \{"name","config"} object binding config to it (e.g. '\[\{"name":"output\_schema","config":\{"schema":\{"type":"object"}}}]'). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tools list`

List the registered tool names.

Example: `tai tools list`

```console theme={null}
$ tai tools list [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tools reload`

Re-register one app tool from its stored definition, fanning out to the fleet.

Example: `tai tools reload example_tool my_tool`

```console theme={null}
$ tai tools reload [OPTIONS] {kind} {name}
```

| Argument | Description |
| - | - |
| `kind` | Tool kind (e.g. "example\_tool"). *(required)* |
| `name` | Tool name. *(required)* |

| Option | Description |
| - | - |
| `--target` `&lt;str&gt;` | A worker to restrict the fan-out to (repeatable). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tools remove`

Remove one app tool from the live registry, fanning out to the fleet.

Example: `tai tools remove example_tool my_tool`

```console theme={null}
$ tai tools remove [OPTIONS] {kind} {name}
```

| Argument | Description |
| - | - |
| `kind` | Tool kind (e.g. "example\_tool"). *(required)* |
| `name` | Tool name. *(required)* |

| Option | Description |
| - | - |
| `--target` `&lt;str&gt;` | A worker to restrict the fan-out to (repeatable). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tools run`

Run a registered tool synchronously and print its run answer: `&#123;kind: result|asks|parked|none, …&#125;`.

Example: `tai tools run add --kw a=1 --kw b=2`

```console theme={null}
$ tai tools run [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Tool name. *(required)* |

| Option | Description |
| - | - |
| `--kwargs` `&lt;str&gt;` | Tool arguments as a JSON object. |
| `--kwargs-file` `&lt;str&gt;` | Read the tool arguments JSON object from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --kwargs; --kw pairs still override its keys. |
| `--kw` `&lt;str&gt;` | A key=value tool argument (repeatable; value parsed as JSON). |
| `--subject-kind` `&lt;str&gt;` | The subject kind an async park of this run indexes under (e.g. 'thread'). |
| `--subject-key` `&lt;str&gt;` | The subject key an async park of this run indexes under. |
| `--subject-target` `&lt;str&gt;` | The subject's target scope name an async park of this run indexes under. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tools runs`

Submit and inspect background (detached) tool runs.

```console theme={null}
$ tai tools runs [OPTIONS] COMMAND [ARGS]...
```

### `tai tools runs get`

Get a background tool run's status and result.

Example: `tai tools runs get abc123`

```console theme={null}
$ tai tools runs get [OPTIONS] {run_id}
```

| Argument | Description |
| - | - |
| `run_id` | Run id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

### `tai tools runs list`

List the recent background runs for a tool.

Example: `tai tools runs list slow_tool`

```console theme={null}
$ tai tools runs list [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Tool name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

### `tai tools runs submit`

Submit a tool for background execution and print its run id.

Example: `tai tools runs submit slow_tool --kw n=100`

```console theme={null}
$ tai tools runs submit [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Tool name. *(required)* |

| Option | Description |
| - | - |
| `--kwargs` `&lt;str&gt;` | Tool arguments as a JSON object. |
| `--kwargs-file` `&lt;str&gt;` | Read the tool arguments JSON object from a file, or from stdin when the path is '-', instead of putting a secret on the command line (a value on argv leaks via ps and shell history). Mutually exclusive with --kwargs; --kw pairs still override its keys. |
| `--kw` `&lt;str&gt;` | A key=value tool argument (repeatable; value parsed as JSON). |
| `--subject-kind` `&lt;str&gt;` | The subject kind an async park of this run indexes under (e.g. 'thread'). |
| `--subject-key` `&lt;str&gt;` | The subject key an async park of this run indexes under. |
| `--subject-target` `&lt;str&gt;` | The subject's target scope name an async park of this run indexes under. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tools schema`

Get one tool's input/output schema.

Example: `tai tools schema my_tool`

```console theme={null}
$ tai tools schema [OPTIONS] {name}
```

| Argument | Description |
| - | - |
| `name` | Tool name. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tools schemas`

Get the input/output schema of every registered tool.

Example: `tai tools schemas --json`

```console theme={null}
$ tai tools schemas [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai tools tags`

List each tool's native tags.

Example: `tai tools tags`

```console theme={null}
$ tai tools tags [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai traces
Source: https://docs.tai42.ai/reference/cli/traces

List and inspect run traces.

List and inspect run traces.

```console theme={null}
$ tai traces [OPTIONS] COMMAND [ARGS]...
```

## `tai traces capabilities`

Show what the monitoring backend serves: the page maximum, the sorts and the sort/filter combinations.

Example: `tai traces capabilities`

```console theme={null}
$ tai traces capabilities [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai traces get`

Get one run's full trace, or download it as JSON with `--export`.

Example: `tai traces get trace_abc`

```console theme={null}
$ tai traces get [OPTIONS] {trace_id}
```

| Argument | Description |
| - | - |
| `trace_id` | Trace id. *(required)* |

| Option | Description |
| - | - |
| `--export` | Download the full trace as a JSON file instead. *(default: `False`)* |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai traces list`

List observability runs, or download the filtered list with `--export`.

Example: `tai traces list --status error --sort cost`

```console theme={null}
$ tai traces list [OPTIONS]
```

| Option | Description |
| - | - |
| `--from` `&lt;str&gt;` | Range start: an ISO instant or a relative token (30d). |
| `--to` `&lt;str&gt;` | Range end: an ISO instant or a relative token. |
| `--status` `&lt;str&gt;` | Filter: 'error' or 'success'. |
| `--sort` `&lt;str&gt;` | Sort field: createdAt, cost, latencyMs, totalTokens. |
| `--dir` `&lt;str&gt;` | Sort direction: asc or desc. |
| `--page` `&lt;int&gt;` | Page number (1-based). |
| `--page-size` `&lt;int&gt;` | Rows per page. |
| `--export` | Download the filtered list instead of paging it. *(default: `False`)* |
| `--format` `&lt;str&gt;` | Export format: csv or json (only with --export). *(default: `csv`)* |
| `--user` `&lt;str&gt;` | Filter: runs stamped with this user identity. |
| `--session` `&lt;str&gt;` | Filter: runs stamped with this session identity. |
| `--version` `&lt;str&gt;` | Filter: runs stamped with this trace version dimension. |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai traces outline`

Get one run's span tree: every span with its parent, kind, status and metadata, without input/output.

Example: `tai traces outline trace_abc`

```console theme={null}
$ tai traces outline [OPTIONS] {trace_id}
```

| Argument | Description |
| - | - |
| `trace_id` | Trace id. *(required)* |

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |

## `tai traces value`

Read one span field's value with every record reference resolved.

Example: `tai traces value trace_abc span_1 --field output --pointer /outputs/n`

```console theme={null}
$ tai traces value [OPTIONS] {trace_id} {span_id}
```

| Argument | Description |
| - | - |
| `trace_id` | Trace id. *(required)* |
| `span_id` | Span (observation) id. *(required)* |

| Option | Description |
| - | - |
| `--field` `&lt;str&gt;` | The span field: input or output. *(default: `input`)* |
| `--pointer` `&lt;str&gt;` | RFC 6901 JSON pointer into the field (e.g. /messages/0). |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# tai version
Source: https://docs.tai42.ai/reference/cli/version

Show the installed tai42 packages and the versions of key CLI dependencies.

Show the installed tai42 packages and the versions of key CLI dependencies.

```console theme={null}
$ tai version [OPTIONS]
```

| Option | Description |
| - | - |
| `--json` / `--no-json` | Emit raw JSON instead of human tables. |


# Conversation bridge
Source: https://docs.tai42.ai/reference/conversation-bridge

Route CRUD and CLI, the read doors, forgetting a thread, retention, the fire-path authorization model, and every bridge setting.

Reference for the [conversation bridge](/concepts/client-conversations): the routing
table, the read and delivery doors, checkpoint and answer retention, the fire-path
authorization model, and every `CONVERSATIONS_*` setting with its default.

Every routing operation requires the Redis conversations backend
(`CONVERSATIONS_REDIS_URL`). With no backend, each one refuses with a loud `501`.

## Routes: CRUD and CLI

| HTTP | CLI | What it does |
| - | - | - |
| `GET /api/conversations` | `tai conversations list` | List routes (each `callback_secret` withheld). |
| `GET /api/conversations/{route_name}` | `tai conversations get <name>` | Read one route; unknown name → `404`. |
| `POST /api/conversations/{route_name}` | `tai conversations create <name> …` | Create **or replace** a route (an upsert). |
| `DELETE /api/conversations/{route_name}` | `tai conversations delete <name>` | Delete a route; unknown name → `404`. |

`create` is an authority-changing, admin-adjacent operation. It checks, in order, and a
refusal at any step leaves an existing row untouched:

1. The `target_name` — the agent or tool the turn runs — must merely exist (`404`
   otherwise).
2. The caller must be allowed to **bind** the route's `execution_key` (a pass-role
   decision).
3. The route write: the target's bind check (a refusal is a `422` carrying the refusal
   lines), then the route's jq programs compile, then a `channel` row's
   `(channel, our_identity)` pair is stored canonical and must be unclaimed. The expression,
   identity and claim refusals are a `400` prefixed `invalid conversation route:` — for example
   `invalid conversation route: invalid start_expr: …` or
   `invalid conversation route: channel 'twilio' identity '+14155238886' is already routed by 'chat-line'`.
   Last, a change of `door` on a route that holds threads is refused with a `400` of its own
   text, for example
   `conversation route 'chat-line' holds 2 thread(s) opened on its 'api' door and cannot be changed to 'channel': delete the route …`.

An `api` row that declares a `callback_url` mints a `callback_secret` returned **once** in
the create result and never re-readable. A [backup restore](/operate/backup-and-restore#restoring-stored-definitions)
runs the same route write (step 3) per row; the target's existence is checked only at this
door.

```bash theme={null}
tai conversations create chat-line \
  --door channel --target-name chat --execution-key chat-bot \
  --channel twilio --identity whatsapp:+14155238886
```

`create` flags: `--door` (`api`|`channel`), `--target-kind` (`agent`|`tool`, default
`agent`), `--target-name`, `--execution-key`, the route's jq programs
`--start-expr` / `--cancel-expr` / `--resume-expr` / `--extras-expr` / `--reply-expr`
(either target kind carries them), `--initial-mode` (`agent`|`manual`, default `agent` — the route's default
[control mode](#operator-messages-and-control-mode)), `--channel` / `--identity`
(channel rows), `--callback-url` (api rows, optional, HTTPS), `--overlap-running` /
`--overlap-deliver` / `--overlap-settle-seconds` (the [overlap policy](#overlapping-messages)).
`--initial-mode manual` is valid on any target (see [control mode](#control-mode)).

## Route targets: agent or tool

A route's `target_kind` chooses what an inbound turn runs:

* **`agent`** (`target_name` a registered agent) — the default. The turn is the
  agent's `astream` on the route's thread, so the conversation carries memory across
  messages (see [conversation
  lifetime](/concepts/client-conversations#conversation-lifetime)).
* **`tool`** (`target_name` a registered tool) — the turn dispatches the tool
  **statelessly**: no conversation memory, one message in and one reply
  out. It runs under the route's `execution_key`, whose grants authorize the
  dispatch.

**Either** target kind carries the route's jq programs, all compiled at create:

* **`start_expr`** — jq over the inbound payload `{message, sender, our_identity,
  channel, route, turn}` — `route` the name of the route the turn entered through, so a
  flow bound to several routes can tell them apart — carrying `person_id` and
  `person_addresses` too when the target's multichannel is on, and `event` on an
  [event turn](#the-event-door) — emitting exactly
  one JSON object: the started run's kwargs (a `tool` dispatch's kwargs, or an `agent`
  run's `astream` kwargs). Omitted, the kwargs are the fixed `{message, sender,
  our_identity, channel, route, turn}` for a tool (plus `event` on an event turn), or the default `{user_message}` from the
  rendered turn text for an agent. An `agent` `start_expr` must not set the route-owned
  run identity (`thread_id` or a checkpoint key), refused at create. `person_id` is the
  person the sending address resolves to and `person_addresses` its address rows;
  `person_id` gives a flow a channel-stable key for a linked person, one and the same
  across the channels they paired.
* **`reply_expr`** — jq over the run's result (the success shape), emitting the reply:
  `null` (silent), a string, or a list of answer parts. Omitted, a tool result must
  itself be a string or `null`, and an agent's structured final is serialized to one
  string. It binds three [variables](/concepts/jq-variables#route-reply): `$turn` (the
  turn ids, subject and reply window this reply answers), `$asks` (the run's caller-ask entries when
  it [asked its caller](/concepts/asking-the-caller) instead of finishing — an empty
  list on a plain result), and `$parked`.
* **`cancel_expr` / `resume_expr` / `extras_expr`** — the [door
  contract](/concepts/asking-the-caller#the-door-contract): `cancel_expr` names parked
  interactions to whole-chain kill (quietly: the channel releases its hold and nothing is
  said to the person), `resume_expr` names an ask to resume with an answer
  (`{id, payload}`) or a waiting outcome to take (a bare id), and `extras_expr` builds
  the `extras` mapping handed to the started target.

Every one of these reads the run's currently parked interactions as
[`$parked`](/concepts/jq-variables#doors) beside its own input.

The payload also carries a **`form`** object when the inbound message brought an
[ask-less form](/concepts/notifications#ask-less-forms) submission — the structured
copy of the values whose rendered text is the `message` itself. The key is present
**only** when the inbound carried one, so a `start_expr` over a form-less inbound
sees a byte-identical payload, and the default no-expr kwargs stay the fixed
`{message, sender, our_identity, channel, route, turn}` either way — a route maps the form deliberately or not at all.
Without a `start_expr` an `agent` target never sees it — it reads the rendered text
only; an `agent` `start_expr` may map `.form` into the run's kwargs exactly as a tool
route does. The values
are bounded as transport (serialized size and nesting) and **never validated against
the form's schema** — participant-shaped data a tool target checks itself. The record
publishes the same object as `inbound_form` on both the admin and caller-safe reads.

The payload also carries a **`params`** object when the inbound entry supplied one —
a web channel's [link parameters](/plugins/tai42/channel-web#link-parameters) captured
with the visitor session, the [message door](#the-message-door)'s `params` body field,
or a channel's **tap enrichment** when the person taps a control the flow offered (a
tapped reply's author-set id as `params.reply_id`, a template quick-reply as
`params.button_payload`, a click-to-chat referral as its `referral_*` fields — what
each channel forwards is on its [plugin page](/plugins)) — string values reachable as
`.params.<name>`. The key is present **only** when the entry carried non-empty params,
so guard for it (`.params.key // …`). The same enrichment rides an
[answer's](/concepts/interactions#enrichment-on-the-answer) `params` when the tap
instead answers a pending `ask`. The values
are **untrusted transport**: the platform caps and delivers them but attaches no
signature, expiry, or meaning, so a value a flow must trust is a secret the flow
checks in its own store. Bounds: at most **16** params, each key
`^[A-Za-z0-9_-]{1,64}$`, each value ≤ **512** characters, ≤ **2048** bytes serialized.
Each door applies one declared policy to a violation:

| Door | `door` label | Over a bound |
| - | - | - |
| Web channel — page, messages, forms, answers | `web` | **refused** (`422`; the page answers a `400` refusal page) |
| Interactions callback (a forwarded answer's `params`) | `interactions-callback` | **refused** (`400 invalid params: …`) |
| Telegram, WhatsApp, Slack, Twilio webhooks | `telegram`, `whatsapp`, `slack`, `twilio` | **dropped** — the set (or one over-cap value) is dropped and the turn proceeds |

A refusing door answers a caller who is waiting; a dropping door's vendor would redeliver a
`5xx` forever, so it never loses the participant's message to a params bound. Every drop is
logged at `WARNING` (naming the door and the bound or key, never a value) and counted on
`tai_entry_params_dropped_total{door, unit}` on `GET /metrics`, where `unit` is `set` or
`value`.

The payload also carries a **`turn`** block on **every** turn — tool and agent targets alike,
whichever door it entered through:

```json theme={null}
{
  "id": "<turn id>",
  "inbound": { "id": "<inbound id>", "kind": "message", "source": "<source>" },
  "subject": { "target_kind": "tool", "target_name": "<target>", "person": null, "thread": "<thread id>", "locale": null },
  "reply_window": { "state": "open", "closes_at": "2026-10-23T09:30:00Z" }
}
```

`turn.id` is the turn's stable id — the answer record's `message_id`, not a new mint.
`turn.inbound` describes the entry: `inbound.kind` is `"message"` or `"event"`,
`inbound.id` is the channel provider message id / the [event](#the-event-door)'s own
`event_id` / (on the api message door) the record's `message_id`, and `inbound.source`
is the channel registry name / `event:<kind>` / `api`. `turn.subject` is the scope a
flow's subject reads: the route's target, the `person` id (null unless the target's
multichannel is on) and the resolved `thread` id, with the turn's `locale`.

`turn.reply_window` says whether a free-form reply can reach the client right now, as the
channel reports it for the pair the turn replies on (`our_identity`, the client's address):

| `state` | Meaning | `closes_at` |
| - | - | - |
| `open` | A free-form reply is allowed until `closes_at`. | The UTC close time, in whole seconds (`YYYY-MM-DDTHH:MM:SSZ`). |
| `closed` | The medium allows only a pre-approved template now. | `null` |
| `none` | The channel has no such window (web, Telegram, Slack, an SMS number), or the turn has no channel (the api door). | `null` |

The window is read once per turn, when the turn starts; a reply delivered later (a parked
tool resumed out of band) reads it again at delivery time. The platform only reports it and
gates no send on it: a flow uses it to choose between a free-form reply and a template, and the
vendor's own refusal of a free-form send outside the window (WhatsApp `131047`, Twilio `63016`)
stays final and fails the delivery loudly. Which channels report a window, and what opens it,
is on each [plugin page](/plugins). A read that fails (the channel's store is unreachable)
ends the turn as a client-safe `error` outcome.

On an **event turn** the payload also carries an **`event`** block `{id, kind, payload}` (the
submitted event) and both `message` and `sender` are `null` — an event has no human sender and
no text; its `turn.reply_window` is the window of the thread's pair. With no `start_expr` a tool
receives the fixed kwargs `{message, sender, our_identity, channel, route, turn}` (plus `event`
on an event turn); a `start_expr` reads `.turn` and `.event` off the payload and forwards what
it needs.

A reply of `null` or blank is a **deliberate silence**, and how it resolves depends
on the door. On a `channel` route the record ends in the terminal `silent` state and
nothing is sent to the client. On an `api` route the silence is **communicated**: the
turn rides the normal delivery pipeline and its callback (or sync-wait reply) carries
`status: "silent"` with no `answer` text, so the caller still gets a terminal result.
A mapping fault, a denied or failed dispatch, a wrong-typed result, or a tool turn
whose run **fails** is a client-safe `error` outcome instead. A failing target raises the
contract's `RunTerminalFailed` (a flow's `error`, `stopped`, or `aborted` terminal arrives
this way), and `reply_expr` maps only a returned result, so a failure never reaches the
mapping and goes straight to the [failure reply](#failure-replies): the target's own reply
when the failure carries one, else the route's error reply.

### A flow preset as a tool target

Publish a flow as a named tool (a [preset](/concepts/presets)) and route to it to
answer each message by running the flow. The flow tool takes `flow_graph_kwargs`, so
map the message into them and pull the reply out of the result envelope:

```bash theme={null}
tai conversations create flow-line \
  --door channel --target-kind tool --target-name my_flow --execution-key svc \
  --channel twilio --identity whatsapp:+14155238886 \
  --start-expr '{flow_graph_kwargs: {message: .message, sender: .sender}}' \
  --reply-expr '.result.answer // null'
```

`.result.answer` is the flow's answer node; `// null` stays silent when the flow
produces nothing to say. This mapping only ever sees the **success** shape: if the
flow or tool turn ends on a non-success terminal status (`aborted`, `stopped`,
`error`) the turn diverts to the `error` outcome and `reply_expr` never runs.

The whole kwargs object is validated against the preset's `input_schema` and routed
into the flow's `flow_graph_kwargs` argument, so with no `start_expr` a flow preset
reads the default kwargs directly as `.flow_graph_kwargs.message`, `.sender`, and
`.turn` (plus `.event` on an [event turn](#the-event-door)) — no route jq needed. A
conversation-target flow preset must therefore admit `turn` (and `event`) in its
`input_schema`; one that declares `additionalProperties: false` without them refuses
the routed kwargs.

Such a flow or tool turn need not answer synchronously: if it raises an async
`ask`, the turn parks and its resumed reply is delivered back into the
originating thread later — mapped through the route's `reply_expr` — the same
deliver-back documented for an agent target. A **step-mode** interrupt is the
exception: a conversation turn cannot drive a step-mode run, so its reply would
never arrive. Rather than silence a pause nothing can resume, the turn diverts to
the loud `error` outcome, naming the misconfiguration in the recorded detail — route
a step-mode tool to a conversation and every inbound fails this way.

## Overlapping messages

By default every inbound message is its own turn, strictly ordered per thread: a second
message that arrives while the first message's turn is still running waits behind it and then
runs its own turn. A route's **`overlap`** policy changes that — it lets a running turn learn a
newer message is waiting, cancel in favour of it, or carry a burst of messages into one turn.
Three knobs on the route, set at create with `--overlap-running` / `--overlap-deliver` /
`--overlap-settle-seconds` (or the `overlap` object on the API body):

| Field | Values | Default | What it does |
| - | - | - | - |
| `running` | `continue` \| `cancel` | `continue` | What happens to the turn in flight when a newer message is accepted on the same thread: `continue` leaves it running (one turn per message), `cancel` cancels it cooperatively in favour of the newer message. |
| `deliver` | `one` \| `all` | `one` | What a turn carries: `one` exactly one message per turn, `all` every message accepted since the last turn started, in order, as one turn. |
| `settle_seconds` | `0`–`30` | `0` | A turn starts no earlier than this many seconds after its **lead** message was accepted, so a burst inside the window rides one turn. `0` disables the window. |

The default policy (`continue` / `one` / `0`) runs one turn per message and leaves the payload
unchanged — the same payload, records, and timing as a route that declares no overlap policy. A `settle_seconds` above `0`
requires `deliver: all` or `running: cancel`; under `continue` + `one` a window would delay
every turn for nothing and is refused loudly at create.

The policy governs **participant message turns only** — records with `origin: client` and an
`inbound_kind` of `message`. An [event turn](#the-event-door) always runs as its own turn: it
is never merged, never superseded, and never cancels a message turn. An
[operator send](#operator-send) runs no turn, and a turn parked on an `ask` is not
"running" — a reply while it is parked resumes through the answer ladder exactly as it does under the default policy.

### The four combinations

Three messages arriving with the first turn already running:

| `running` | `deliver` | Turns that complete | What each carries |
| - | - | - | - |
| `continue` | `one` | three | 1; 2; 3 — the default: one turn per message. |
| `continue` | `all` | two | 1; then one turn carrying 2 and 3. |
| `cancel` | `one` | one | 1 cancelled (`superseded`), 2 `superseded` (by 3), one turn on 3. |
| `cancel` | `all` | one | 1 cancelled, one turn carrying 2 and 3 with 1 in `superseded`. |

### The settle window

`settle_seconds` holds a turn back until that many seconds have passed since its **lead**
message was accepted — a fixed window from the lead, never sliding, so the wait is bounded and
a stream cannot starve it. A burst that lands inside the window rides one turn (under
`deliver: all`) or is superseded by the newest (under `cancel`). The turn's intake lease keeps
refreshing through the wait, so the turn is never re-driven while it settles.

### What cancellation can and cannot do

`cancel` is **cooperative**. A newer message sets a per-thread marker; a watcher armed around
the running turn's body cancels the owner task, and the turn stops at its **next `await`** —
resolving `superseded` in favour of the newer message, with no reply and no delivery. It
cannot interrupt a **synchronous** tool body already offloaded to a thread: that body runs to
completion in the background and its result is dropped. Delivered messages and state writes are
never reverted — a cancelled turn's partial state stays in the state module and the next turn
reads it as its starting document; reverting is the handler's job. A tool body can cooperate
where the watcher cannot reach: it reads the [pending
seam](/concepts/client-conversations#when-messages-overlap) and yields early by raising
`TurnSupersededError`, so an expensive or irreversible step never runs past a newer message.
`TurnSupersededError` is a `BaseException`, not an `Exception`, so no broad `except Exception`
between the yielding body and the platform's turn runner — which catches it explicitly — ever
swallows the yield.

### The carried payload

Under `deliver: one` the tool payload is unchanged from the default. Under `deliver: all` (a
`tool` target) the payload gains two keys:

* **`messages`** — the batch in order, each `{id, text, accepted_at}`, plus `form` /
  `attachments` / `location` / `reply_to` when that message carried them (`reply_to` is the
  message it [replied to](#replies-to-an-earlier-message)).
* **`superseded`** — present only when non-empty: the earlier messages dropped in favour of
  this turn, in the same shape.

`message` becomes the turn's **whole** text: the superseded texts then the batch texts, in
acceptance order, joined with a blank line — so a route with no `start_expr` and an `agent`
target both see the whole turn with no new seam. A manual-mode thread appends the whole turn
to its memory — the superseded texts then the batch texts, the same order as the joined
`message`. The lead's own
top-level `form` / `attachments` / `location` / `reply_to` keys stay the lead's. Map `messages` and
`superseded` in a `start_expr` exactly as any other payload key.

### The overlap outcomes

A message handed to another turn ends in one of two answerless terminal outcomes, each naming
the turn that took its place through **`successor_id`** (the successor turn's `message_id`):

* **`merged`** — this message's text was carried into the named turn (under `deliver: all`).
* **`superseded`** — this message was dropped in favour of the named turn (a running turn
  cancelled by a newer message, or a queued message overtaken by a newer one on a `cancel`
  route).

The two doors deliver the outcome as they deliver `silent`:

* **Channel door** — a terminal record, answerless; nothing is ever sent back.
* **API door** — the record rides the delivery pipeline and is delivered as a marker: the
  callback (or sync-wait reply, or poll-door record) carries `status: "merged"` /
  `"superseded"` and the `successor_id`, no answer text, so the caller learns its message's fate
  and where the answer will be.

### The cancel marker and its setting

On a `running: cancel` route every participant message accept writes a per-thread marker in the
conversations Redis — `<prefix>:overlap:cancel:{thread_id}` = `{message_id, created_at}`, TTL
the thread lease — naming the newest message on the thread. The watcher a running turn arms
reads it every `overlap_cancel_poll_seconds` and cancels the turn when the marker names a
message newer than the turn's batch. The marker lives in the shared Redis and the watcher runs
in the turn's holder, so cancellation works across workers with no local fast path.
`overlap_cancel_poll_seconds` (default `0.5`) must stay **below** `thread_lease_seconds`, or the
marker could expire before the watcher next reads it. See [Settings](#settings).

## The message door

`POST /api/conversations/{route_name}/messages` (authed) accepts one API-door
message and runs its turn as the route's execution key. Body: `external_user_id`,
`text`, optional `wait_seconds`, optional `params`, optional `form`, optional
`attachments`, optional `location`, optional `reply_to_message_id`.

`form` is an optional structured participant submission (an
[ask-less form](/concepts/notifications#ask-less-forms)'s answers) riding **with**
the required `text` — the text stays the carrier every consumer sees, while a tool
target's payload gains the structured copy under its `form` key. It must be a JSON
object within the transport bounds (serialized size and nesting); a violation is a
loud `400`, and the refusal never echoes the submitted values. Nothing validates the
object against any schema — it is participant data.

`params` is an optional object of string values delivered to a **tool** target's
payload under `.params` — the same key a channel entry's link parameters use — for a
uniform tool-payload contract across both doors. It is validated to the same bounds
(at most 16 entries, key `^[A-Za-z0-9_-]{1,64}$`, value ≤ 512 characters, ≤ 2048
bytes); an invalid set is a `400` that names the violated bound **without echoing the
offending value**.

`attachments` and `location` are the media and geographic siblings of `form` — a list
of `MediaItem`s (image/document/video/audio) the caller sent with the text, and a
shared `LocationElement` (latitude/longitude with an optional name/address). Each
rides **beside** the required `text` (which stays the whole turn every reader
consumes) and reaches a **tool** target's payload under its own `attachments` /
`location` key, present only when supplied. `attachments` obeys the shared media caps;
both are untrusted transport, never schema-validated. See
[structured participant messages](/concepts/client-conversations#structured-participant-messages).

`reply_to_message_id` names the message this one replies to: the platform `message_id` of a
message the platform delivered to the caller under it — the `message_id` on a `200` answer,
in a signed callback body, or on a poll-door record. The platform resolves it against the
same thread's records into the text delivered under that id (a turn's answer, an operator's
hand-sent message, an event turn's answer) and hands it on as
[`reply_to`](#replies-to-an-earlier-message). An id that names nothing in this thread reads
`not_found`; an id under which nothing with text was delivered — a `silent`, `merged` or
`superseded` marker, an answer of media only, a turn not finished yet — reads `no_text`. The
caller's own submitted text is not what the id quotes. The value must be a UUID4; anything
else is a `400`.

* `202 {message_id, thread_id}` — accepted; the answer is delivered later by the
  route's signed callback, or — when the route declares no `callback_url` — read back
  from `GET /api/conversations/{route_name}/messages/{message_id}`.
* `200` with the answer inline — a `wait_seconds` turn that finished in time; a route
  with a callback suppresses it so it never double-fires. A turn that finished **silent**
  returns `200` with the silent marker inline (`status: "silent"`, no answer text).
  `wait_seconds` is clamped to `sync_wait_max_seconds`. The inline answer is returned
  **only while the caller is still connected**; a caller that hung up is answered by the
  route's signed callback, or on a poll-only route by the poll door. A hang-up in the
  instant the response is written still reads `delivered` at the poll door.
* Refusals are loud: `400` bad body, `401` unauthorized, `404` unknown route, `429`
  address rate cap, `501` no backend, `503` thread queue full.

> [!NOTE]
>
> **In-process face.** A run inside the deployment sends to this door with the builtin
> `send_conversation_message` tool — no HTTP request and no route key handed to the run.
> The turn runs **as** the route's execution key; the run's execution identity is the
> accountable principal the door buckets on, and the **same** authorization the HTTP door
> applies is applied first. Its `reply_to_message_id` argument is the same field, under the
> same rules. The tool returns the accepted receipt at once — its answer is
> delivered by the route's own configured delivery, never inline.

### Replies to an earlier message

When a person's message replies to an earlier message, the platform looks the earlier
message up in the conversation's own records and hands the turn a typed **`reply_to`**
beside the text: the quoted message's text, or the reason there is none. The text comes
from the conversation record of the same thread, never from the medium, so it lives as long
as that record does (the [retention](#checkpoint-retention) of the thread's answer records)
and is forgotten with it.

Each medium marks a reply its own way; the channel passes on only the id of the message
replied to:

| Channel | What marks a reply |
| - | - |
| WhatsApp | `context.id` on the inbound message: the message replied to. |
| Telegram | `reply_to_message` in the same chat. A message from another chat or topic (`external_reply`) names no message of this chat and quotes none; a forum-topic message whose `reply_to_message` is the topic's first message is a reply only when the person replied to another message. |
| Slack | `thread_ts` on a thread reply: the thread's parent message. Slack has threads, not per-message replies, so a reply in a thread quotes the parent; the parent itself quotes nothing. |
| Twilio | `OriginalRepliedMessageSid`, sent only for WhatsApp over Twilio and only for a reply to a message of the last 7 days. An SMS has no reply field. |
| Web | None: the chat widget has no reply action. |
| API door | The body's `reply_to_message_id` ([the message door](#the-message-door)). |

A **button tap** is a reply to the tapped message on WhatsApp, Telegram and Slack: a tap
that answers a question quotes the question. Twilio sends no buttons, and a Slack modal
submission names no message, so it quotes none.

`reply_to` is `{message_id, status, text}`. `message_id` is the id the person's side names
the quoted message by — the medium's message id on a channel, the platform `message_id` on
the API door. `text` is set only when `status` is `found`:

| `status` | Meaning |
| - | - |
| `found` | The thread's record holds the quoted message; `text` is its text. A message the medium sent as several records (one per file) quotes as their texts joined by a blank line. |
| `not_found` | Replying to a message this thread's record does not hold. It may be in an earlier thread of this conversation, whose text is not shown here, or it expired, was forgotten or was never recorded. |
| `sensitive` | The quoted message is an answer to a [sensitive question](/concepts/secret-values#sensitive-questions); its text is never kept. |
| `no_text` | The record holds the message and it has no text — a media-only message, or on the API door a record under which no text was delivered. |

A quote is looked up only in the thread the reply arrives in, never under another address
or caller. A person who [links a second address](/guides/link-a-person-across-channels)
writes in their `bridge:@person:{person_id}` thread from then on, while a message quoted
from before the link stays in the route's own thread, so it reads `not_found` (and the
reverse after the person is erased). A deployment with no conversations store looks nothing
up.

A `tool` target reads the quote under its payload's `reply_to` key, present only when the
message replied to one; an `agent` target reads it through its `start_expr`. The record
keeps it as `inbound_reply_to`, which the [read doors](#the-read-doors) serve.

When the reply **answers a pending question**, the asker receives the same `reply_to`
beside the unchanged answer, resolved in the question's own thread (see [Block or park:
sync and async](/guides/use-interactions#block-or-park-sync-and-async)). The question's
send record keeps it as `ask_reply.reply_to`.

### Inbound media

When a participant sends media (a photo, document, voice or audio clip, video, file, or
sticker), the channel bridges it as a normal turn: the caption becomes the turn text, or,
with no caption, a short non-blank placeholder such as `[image]`, `[document: report.pdf]`,
or `[voice message]`. The media's identity rides the turn's `params` under a generic
vocabulary — `media_kind`, `media_id`, `media_mime_type`, `media_filename`, `media_sha256`,
`media_voice`, `sticker_animated`, and, where the channel reports it, `media_size` — where
`media_id` is the reference the producing channel can later resolve. Each value obeys the
standard per-value parameter cap; an over-cap value is dropped rather than truncated, and the
turn still bridges. This vocabulary carries the media's identity only: no bytes are fetched or
stored for it.

On the channels that **ingest bytes**, the bridged turn additionally carries typed
`attachments`: the platform has fetched the file, verified it, and stored it by reference, and
each attachment is a **served reference** — a same-origin capability URL
(`/api/interactions/media/{media_id}`) a tool, an agent's `start_expr`, or the operator
console can render or download. The parity `media_*` params still ride the turn, now filled
from the stored file's real size, hash, and type. If the file cannot be received — it is over
the per-kind cap, its type is not allowed, the byte source could not be fetched, or no storage
provider is configured — no attachment is minted; the participant is told and the drop is
recorded on the [`conversations_inbound_rejected`](#inbound-platform-events) event with a
`reason` of `too_large`, `unsupported_type`, or `could_not_receive`. See the [operations
storage page](/operate/storage) for the ingestion requirements and the per-kind caps.

### Inbound platform events

The inbound path emits two platform events a deployment can wire a hook to. Neither is a reply
and neither returns an error to the provider — the inbound is always acknowledged so a
provider does not redeliver in a loop; the event makes an otherwise-silent drop visible.

* **`conversations_inbound_rejected`** — emitted when a channel receives content it recognises
  but cannot bridge as a turn, carrying a `reason`: `unsupported_type` (no mappable content, or
  the provider signalled a message type it will not deliver — for example a WhatsApp
  "unsupported message type" notice), `too_large` (a byte-ingested file over its per-kind cap),
  or `could_not_receive` (the byte source could not be fetched, or no storage provider is
  configured). The participant receives the route's own notice for that reason when the route
  sets one (`reply_texts.rejected_unsupported_type`, `rejected_too_large` or
  `rejected_could_not_receive`), else one fixed generic notice — `"This content type is not
  supported here."`, `"That file is too large to accept here."`, or `"That attachment could not
  be received."` — and this event records the drop, so unsupported content is visible rather
  than silently discarded.
* **`conversations_inbound_unrouted`** — emitted when a reply arrives for an address with no
  bound conversation route. It is distinct from a rejection: an unrouted reply and a
  recognised-but-unbridgeable content are different faults.

### The working-on-it signal

While the platform works on a reply to a bridged inbound message it shows the channel's own
"working-on-it" indicator — the typing dots on WhatsApp and Telegram — and refreshes it under
the vendor's short expiry so it does not lapse mid-turn. The indicator stops the instant the
reply is sent, when the record leaves the in-flight delivery states, or when the turn ends
with no send; a hard ceiling bounds a turn that never sends. It is best-effort and cosmetic: a
signal failure never reaches the turn.

Two settings tune it (`CONVERSATIONS_` prefix; see [Settings](#settings) for defaults):

* `CONVERSATIONS_WORKING_SIGNAL_MAX_SECONDS` — the hard ceiling on one turn's refresh loop;
  `0` disables the loop entirely (the kill switch).
* `CONVERSATIONS_WORKING_SIGNAL_REFRESH_MARGIN_SECONDS` — the margin subtracted from the
  vendor indicator's lifetime to choose the refresh interval, so each refresh lands before it
  lapses.

Not every channel drives it: Slack and Twilio show none (their API offers no bot typing
indicator), and the web chat page shows its own client-side typing indicator rather than a
server-driven refresh.

## The event door

`POST /api/conversations/{route_name}/events` (authed) delivers a **structured event**
into an **existing** thread as a turn. An event carries no human text: it runs the
route's `tool` target through the same per-thread FIFO an inbound message takes — as a
turn, never a detached [tool run](/studio/running-tools) — so it is ordered behind any
message turn already on the thread. It never mints a thread. On a linked-person thread the
event turn's payload carries `person_id` and `person_addresses` exactly as a message turn
does — the existing person is resolved read-only, never provisioned.

Body (`ConversationEventSubmission`):

```json theme={null}
{
  "address": "<the thread's client address>",
  "thread_id": "<or the thread id the listing exposes>",
  "event": { "event_id": "<idempotency key>", "kind": "provider.update", "payload": {} },
  "wait_seconds": 0
}
```

* **`address` XOR `thread_id`** — exactly one, non-blank, names the target thread; both
  or neither is a `400`.
* **`event.event_id`** — the idempotency key: non-blank after trimming, ≤ 256 characters.
* **`event.kind`** — an identifier-like label matching `^[A-Za-z0-9_.:-]{1,128}$` (dotted
  and colon-segmented labels like `provider.update` are admitted); it becomes the turn's
  `inbound.source` as `event:<kind>`.
* **`event.payload`** — an opaque JSON object, bounded as pure transport exactly like the
  message door's `form` (a serialized-size and nesting cap); never validated against any
  schema.
* **`wait_seconds`** — the same bounded sync-wait window as the message door, clamped to
  `sync_wait_max_seconds`; `0` (the default) is an async `202`.

Responses:

* `200` with the answer inline — a `wait_seconds` turn on an **api**-door thread that
  finished in time; a route with a callback suppresses it so it never double-fires. The
  inline answer is returned **only while the caller is still connected**; a caller that
  hung up is answered by the route's signed callback, or on a poll-only route by the
  poll door. A hang-up in the instant the response is written still reads `delivered` at
  the poll door.
* `202 {message_id, thread_id}` — accepted; the answer is delivered later by the target
  route's door (a channel send, an api route's signed callback, or — when the api route
  declares no callback — the poll door, `GET /api/conversations/{route_name}/messages/{message_id}`).
* `404` — the thread does not exist on the route (an event enters an existing thread, so
  an unknown `(route, address)` or `thread_id` is refused, never opened).
* `409` — the route's target is an **agent**: an event has no rendered text to hand an
  agent, so only a `tool` target may run one.
* `400` — a bad body: the `address`/`thread_id` rule, a blank/over-long
  `event_id`, a malformed `kind`, or an over-bound `payload`.
* `400` — a `thread_id` naming a linked person's thread whose records are all send records:
  `thread <id> holds no message from the participant to address the event to; submit the event by address`.
  On a linked person's thread the event goes where the person last wrote
  from, and a send record does not count as writing.
* Also loud: `401` unauthorized, `429` address rate cap, `501` no backend, `503` thread
  queue full.

**Idempotency.** The door is idempotent on `event_id`, per route, in its own key family
(`conversations:event-dedupe:{route_name}:{event_id}`, held for `inbound_dedupe_ttl_seconds`
— never the channel dedupe namespace). A redelivered `event_id` starts **no** second turn
and returns the **original** turn's `message_id` (a `202`). A refused or failed admission
— a rate cap, a full queue — never burns the key, so a retry after one runs cleanly.

**Thread addressing.** The thread must already exist on the route; the platform recomposes
the id through the same function the route's own door uses, never trusting a caller-composed
key. By `address`: a **channel** route composes the address exactly as its channel door
does; an **api** route qualifies the address by the calling principal (as the message door
does), so by `address` a caller reaches only its **own** threads on that route — another
principal's api thread is reachable only by its listed `thread_id`. By `thread_id`: the id
the [thread listing](#the-thread-listing) or [transcript](#the-transcript) returns,
verified to be a member of the route's threads.

**Delivery** follows the **target** route's door: a channel route's answer is sent to the
thread's address; an api route's answer is POSTed to the **route's** `callback_url`, signed
with the route's `callback_secret` — or returned inline on a bounded `wait_seconds`, or
recorded only when the route has no callback (retrievable through
`GET /api/conversations/{route_name}/messages/{message_id}`). There is **no** per-request
callback field: a caller-named sink would make the platform emit a validly signed POST to
an arbitrary host.

> [!NOTE]
>
> **In-process face.** A run delivers an event to this door with the builtin
> `send_conversation_event` tool — no HTTP request, no route key. It runs the route's
> **tool** target as the route's execution key, applies the same authorization the HTTP
> event door applies, addresses the existing thread by `thread_id` or `address`, and
> returns the accepted receipt; the answer rides the target route's own delivery. Like
> the HTTP door it is idempotent on `event.event_id`.

> [!NOTE]
>
> **The event door is a trusted-integration surface.** Authorization is the conversations
> **write** action with a mandatory caller principal — the same primitive that creates a
> route. An authorized writer may address **any** existing thread of the route by
> `thread_id`, a channel participant's thread included, so grant the door's write action to
> **service principals**, not to low-trust API keys.

## The read doors

| HTTP | CLI | Scope |
| - | - | - |
| `GET /api/conversations/{route_name}/messages/{message_id}` | `tai conversations get-message <route> <id>` | Read grant. |
| `GET /api/conversations/messages/failed` | `tai conversations failed` | Admin only. |
| `GET /api/conversations/{route_name}/threads` | `tai conversations threads <route>` | Admin only. |
| `GET /api/conversations/{route_name}/messages/search?q=` | `tai conversations search <route> --q …` | Admin only. |
| `GET /api/conversations/{route_name}/transcript?thread_id=` | `tai conversations transcript <route> <thread>` | Read grant. |

The single-record door is a plain authed read gated by the **conversations read
grant**: a holder reads any record on the route, whichever door it arrived through. An
admin read returns the full record (including `error`, the turn's internal detail, and the
delivery bookkeeping such as `pending_receipt`); a non-admin read returns a caller-safe
projection that withholds `error` and the delivery bookkeeping — the turn ran as the
**route's** key, not the reader's. A record on another route (or missing) is a `404` — a
wrong-route or unknown address, never an authorization verdict.

Every record carries an `origin` — `client` for an inbound message's turn, `operator`
for a message an operator sent into the thread [by
hand](#operator-messages-and-control-mode), `send` for a message the platform sent to a
participant on its own (see [send records](#send-records)) — published in both the admin
and the caller-safe projections. A record whose inbound message brought an
[ask-less form](/concepts/notifications#ask-less-forms) submission also publishes the
structured object as **`inbound_form`**, in both projections, beside the rendered
`inbound_text` that stays the message every consumer reads.

The transcript page carries `person_id` beside its records: the linked person a
`bridge:@person:{person_id}` thread aggregates, `null` for a route-keyed thread. A thread
that answers the uniform `404` carries none.

**Unreadable rows are counted, not hidden.** Every listing — the thread listing, message
search, the transcript, and the route and config listings — returns an `unreadable` count
beside its rows. A stored row the platform cannot decode, or whose row has gone from under its
index, is tallied there and omitted from the returned items, so a shorter-than-expected
listing carries a nonzero `unreadable` you can act on rather than a silent gap.

**A record whose route was deleted still stands.** A conversation record accepted while its
route was being removed is kept and delivered, and carries `route_missing: true` in both the
admin and caller-safe reads. Because its thread indexes were never written, no transcript
names it — the flag is how you recognise such an orphaned-route record rather than assuming it
was lost, and the platform logs the orphaned record loudly when it is created. A send record
that completes or ends while its route is being removed is kept the same way, with
`route_missing: true`, and no transcript names it.

The failed-delivery listing spans every route and caller, so it is admin-only.

### The thread listing

`GET /api/conversations/{route_name}/threads` lists the route's threads, **newest
activity first**, one page at a time. It is **admin-only** — a listing spans every
caller and every address on the route — and the authorization is decided *before* the
route is looked up, so a non-admin is refused identically whether the name routes or
not.

| Query | Default | Meaning |
| - | - | - |
| `page` | `1` | 1-based page number; at most `1000000`. |
| `pageSize` | `50` | Items per page. A larger value is **capped to 200**, never refused. |
| `status` | *(none)* | Keep only threads whose newest record's `delivery_status` is this one. |
| `address` | *(none)* | Keep only threads whose id client-address suffix **contains** this substring. |

The answer is `{items, total, page, page_size, next_page, truncated}`, where `total` counts
the route's indexed threads (or, under a filter, the matches the scan found), `next_page` is
`null` on the last page, and `truncated` is described below. Each item carries:

| Field | Meaning |
| - | - |
| `thread_id` | The thread's addressable identity — what the transcript door takes. |
| `client_address` | The client address of the thread's newest readable record. |
| `last_activity_at` | Epoch seconds; the route index's own score, which is what the listing sorts by. |
| `message_count` | Exchanges the thread holds. |
| `last_delivery_status` | The delivery state of the thread's newest readable record. |

A send record counts like any other record: a thread a send started is listed, its
`message_count` includes the send, and when the newest record is a send its address and
delivery state are the ones shown.

`status` is validated against the delivery-status vocabulary (`accepted`,
`pending_delivery`, `sending`, `provisional`, `delivered`, `failed`, `outcome_unknown`,
`shed`, `silent`, `merged`, `superseded`); `outcome_unknown` can match a thread, while
`sending` never matches one, because a send still going out is not in any thread yet. An
unknown value is a **loud `400`**, never a silently ignored filter.

> [!NOTE]
>
> **Filters are a bounded post-scan.** The per-status indexes are global over message ids, not
> per-route thread ids, and an address has no index at all, so `status`/`address` are an
> app-side scan bounded by a fixed budget. A page that spends its budget before the route is
> exhausted answers **`truncated: true`** — matches may lie beyond it. An unfiltered listing
> never scans and is never truncated. `truncated` is always present, so a client reads it on
> every page rather than inferring completeness.

Refusals: `400` a non-integer, sub-1, or too-large window, or an unknown `status`; `401`
unauthorized; `403` a non-admin caller; `404` an unknown route; `501` no conversations
backend.

### Searching a route's messages

`GET /api/conversations/{route_name}/messages/search?q=…`
(`tai conversations search <route> --q …`) returns every record on the route whose inbound
text or answer **contains** `q`, across all its threads, newest-active thread first. It is
**admin-only** (it spans every caller on the route) and each item is the **whole record** —
the same shape the transcript serves an admin. `q` is REQUIRED and non-blank.

| Query | Default | Meaning |
| - | - | - |
| `q` | *(required)* | The text to search the route's records for. |
| `page` / `pageSize` | `1` / `50` | The same window as the listing; `pageSize` caps at 200. |

The answer is `{items, total, page, page_size, next_page, truncated}`. There is no per-route
record index, so the search is a bounded nested scan (the route's threads, then each thread's
records); a page that spends its budget answers `truncated: true`. Refusals: a blank/absent
`q` or a malformed window is `400`; a non-admin is `403`; an unknown route is `404`; no
backend is `501`.

### The transcript

`GET /api/conversations/{route_name}/transcript?thread_id=…` reads one thread's
records, one page at a time. The thread id rides the **query string**, not the path:
an API-door id carries a percent-encoded principal that no path spelling round-trips,
and a query value is decoded exactly once whatever it holds.

| Query | Default | Meaning |
| - | - | - |
| `thread_id` | *(required)* | The thread to read, spelled as the listing returned it. |
| `page` / `pageSize` | `1` / `50` | The same window as the listing; `pageSize` caps at 200. |
| `order` | `asc` | `asc` reads oldest first; `desc` reads newest first, so page 1 always holds the latest — the order a live tail wants. |
| `q` | *(none)* | Keep only records whose inbound text or answer **contains** this substring. |

The answer is `{items, total, page, page_size, next_page, order, truncated}`, its items the
same answer records the single-record door serves — whole records for an admin, the
caller-safe projection otherwise.

> [!NOTE]
>
> `q` is a **bounded text search** over the record content (the searched text lives inside the
> record's JSON blob), so a page that spends its scan budget answers `truncated: true`. Under
> `q`, `total` is the number of matches found, and a thread that exists but **matches nothing**
> reads as an **empty page**, never a `404` — the unknown-thread `404` below is reserved for a
> thread the index does not hold at all.

The transcript is a plain authed read gated by the **conversations read grant** — a
holder reads any thread on the route, whichever door its messages arrived through: an
API-door thread, a linked person's `bridge:@person:{person_id}` thread, or a channel
thread alike. Only the two listings stay admin-only (each spans every caller and
address on the route); a single thread read does not.

A `404` here is an **addressing** verdict, never an authorization one: an unknown
thread, an expired one, or a `route_name` that does not route at all. A blank
`thread_id`, an unknown `order`, or a malformed window is `400`; a caller without the
read grant is `403`; no backend is `501`.

> [!NOTE]
>
> A thread the index still holds but whose records have expired under
> `answer_retention_ttl_seconds` reads as an **empty page carrying the indexed
> `total`** — not a `404` — until the prune pass reclaims the members.

### Send records

Every message the platform sends to a participant on a channel with a bridge route is
recorded in that participant's thread, as a record with `origin: "send"`: a `notify_user`
send, a question an `ask` delivers on a channel, the platform's own notices (a refusal, an
ask retry or closed notice, a rejected-inbound notice), and a message a channel plugin sends
on its own. The record carries the text in `answer` and an empty `inbound_text`. A send on a
channel with no bridge route, or on a deployment with no conversations store, still goes
out and is not recorded.

| Field | Meaning |
| - | - |
| `sent_by` | The path the send took: `notify` (every `notify_user` door alike, whoever called it), `ask`, `notice` (a platform notice) or `channel` (a message a channel plugin sent on its own). |
| `turn_message_id` | The `message_id` of the turn the send was made in, set only when the send went to that turn's own participant; `null` on a send outside a turn. It is what marks a send made inside a turn. |
| `ask` | On an ask: `interaction_id`, `answer_format`, `sensitive`, `attempts` and `timed_out_attempts`. The caller-safe projection keeps `sensitive` only. |
| `ask_reply` | The participant's reply over the channel: `answer`, `answered_at`, `medium_message_id` and `reply_to` (the message the reply [quoted](#replies-to-an-earlier-message), or `null`). The caller-safe projection keeps `answer` and `reply_to`. |
| `sends` | Admin only: one entry per part sent, `{part, chars, provider_message_ids}`. |

A send lands in the thread an inbound message from the same participant would use, and may
start it; a later message from them continues it. A completed send is placed by the address
the medium reports (so a Telegram send to an `@username` lands in the thread of its numeric
chat), a send that never completed by the address resolved before sending. A send made
during a turn to that turn's participant stays in the turn's thread.

Only a reply that came over the channel is recorded in `ask_reply`. For a question asked
as `sensitive` the record keeps that the reply came, when, and its message id, never its
body: `answer` is `null` in every view, and the transcript, message search and a quote of
that reply show no body. An answer given through the answer door, or a caller resume,
writes nothing to the record: it keeps the delivery state its send reached and has no
`ask_reply`.

Message search (`q`) also matches the text of an `ask_reply` answer.

A participant record carries `inbound_reply_to`: the message it
[quoted](#replies-to-an-earlier-message) as `{message_id, status, text}`, or `null`. Both
the admin and the caller-safe view serve it. Operator, send and event records never carry
one.

## Forgetting a thread

`DELETE /api/conversations/{route_name}/thread?thread_id=…`
(`tai conversations delete-thread <route> <thread>`) **forgets** one thread
outright — its agent checkpoint, its answer records, its thread indexes, and the
thread's [declared-state](/concepts/states) records — so a later message on the same
address starts a memory the deleted turns never touched. It is a **complete forget**:
the transcript and the conversation's own declared-state memory both go, not just the
transcript. A linked person's aggregated `bridge:@person:{person_id}` thread is
forgotten across every route index it spans, including a route one of the person's
addresses was later unlinked from and a route a send to the person used.

The thread id rides the **query string**, exactly as the transcript door takes it: an
API-door id carries a percent-encoded principal that no path spelling round-trips.

Forgetting is **absolute**. A valid id on its own route always succeeds, and the
answer's `removed` count is `0` when nothing was left to clear — an aged-out thread
whose records already expired under `answer_retention_ttl_seconds`, or one never seen
— never a `404`. The checkpoint is deleted regardless, so retained memory is not
left behind once the records lapse.

The forgotten records include the thread's send records and their ask replies. Each
record's message-refs, outbound receipt index entries and ask index entry are removed in
the same step as the record, so a later quote of one of its messages resolves to nothing,
and a delivery receipt for one of them reaches only the run trace. A reply over the channel
to a question of the forgotten thread is not recorded (a WARNING is logged when the forget
lands while the reply is being written). A send still going out when the thread is
forgotten is forgotten with it when it ends in that thread: the message may still reach
the participant, but no record of it is kept, the thread is not re-created, and a WARNING
names the record. A send whose medium answer places it in another thread (a handle
resolved to a numeric chat id) is recorded in that thread. A quote's text lives only on the
records this deletes, so it is forgotten with them. A parked ask in the forgotten thread is
withdrawn before any record is deleted, so no continuation runs with a quote; a synchronous
ask still waiting reads `not_found` for a quote into the forgotten thread.

Authority is the door's **write** action — the **same conversations write grant that
creates a route** deletes routes and forgets threads, never a per-thread owner check.

The answer is `{removed, states_erased, route_name, thread_id}`, where `removed`
counts the answer records cleared and `states_erased` counts the thread-subject
[declared-state](/concepts/states) records this call forgot across the routes the
thread spans — `0` when the states feature is off or the thread held no declared
state. The reset clears the thread's own **`thread`-subject** state only — the
conversation's memory keyed on this thread; declared state a flow scoped to the
`person` (deliberate cross-thread memory) is cleared by [forgetting the
person](#forgetting-a-person), not a single-thread reset. State erasure runs last under
the same in-flight/FIFO guard, so a live turn can never race it; a failure there raises
loudly and the idempotent call is retried.

Refusals: a route-keyed id missing
the route's `bridge:{route_name}:` prefix is a `400` (it names another route) — the
one guard stopping a delete on one route from wiping another's memory; a
`bridge:@person:` thread whose person is unknown, or whose `route_name` is not one of
that person's routes, is a `404`; a turn in flight on the thread is a `409` (retry
once it drains); a blank `thread_id` or invalid `route_name` is a `400`; no backend
is `501`.

## Forgetting a person

`DELETE /api/conversations/persons/{person_id}`
(`tai conversations delete-person <person_id>`) **erases a linked person ENTIRELY** — every
store scoped to that identity:

* its aggregated `bridge:@person:{person_id}` thread — the agent checkpoint, and across
  **every route the person wrote under** (including a route one of its addresses was later
  unlinked from, and a route a send to the person used) its answer records, per-thread transcript indexes,
  route-thread index memberships and per-thread mode override (the [thread-forget
  machinery](#forgetting-a-thread), reused);
* its [declared-state](/concepts/states) records — both the person's own
  **`person`-subject** memory (the cross-thread memory a flow scoped to the person) and the
  aggregated thread's **`thread`-subject** memory, across every route the person spans;
* the person row `conversations:person:{person_id}`;
* **every** `person_index` `door_address_key → person_id` mapping of its addresses;
* **every thread only this person and the persons it absorbed wrote in**, on every route:
  the chat each of its addresses had on its own channel, before and after a link, written
  by a message or by a send alone, including on a route deleted or moved to another target
  since, each with its checkpoint, records and indexes and its `thread`-subject declared
  state. On a route deleted before the erase, that thread's records are left to their
  retention period, as the route delete leaves them; its checkpoint and state are cleared.
* **every person it absorbed by a link** (a `/link` keeps the person created first and
  absorbs the other; a chain of links is followed to its end): each absorbed person's own
  `bridge:@person:{id}` thread on every route it wrote under, with its checkpoint, records
  and indexes, and its `person`-subject declared state, cleared before the person row goes.

**A thread another person also wrote in is left to them**: a chat someone else wrote in
before the link, or continued after it (an address unlinked from the person and written on
by whoever holds it now, or a route edited or created again under its name and written on
under its new target or number). It keeps its messages until their retention period, is
not counted in `removed`, and a turn in flight in it is no `409`: the erase waits for the
turn before leaving the thread, up to the same bound as for a thread it clears. It is
cleared once every person who wrote in it has been erased, or by the erase of a person who
absorbed them all, even when their erases run at the same time.

The person's own replies and sends that land in a thread after a link are cleared with that
thread. A message that lands in a thread while the erase is clearing it is cleared with it,
whoever sent it, as for a thread deleted while a message arrives. A message to or from one
of the person's addresses that lands in a thread after that thread was cleared (by this
erase, by the erase of the other person in a chat it left to them, or by a
[thread delete](#forgetting-a-thread)) is kept: it starts that thread again, and it is
cleared by the erase of whoever next holds that address, whether or not they write in that
thread, by a thread delete, or by the erase of another person who wrote in that chat
before. One that lands in a chat left to another person who still writes there stays with
that chat and is cleared by that person's erase. When an erase stops part-way with an error
and someone else writes in a thread it was clearing before the retry, the retry leaves that
thread to them. An erase that fails does not bring back what it already cleared, and that
includes a chat shared with another person that this person's erase was leaving to them:
if that person's own erase cleared the chat while the failed erase ran, it stays cleared.
A message from one of the person's addresses that starts a thread on another route in the
last moment of the erase makes the erase answer `409` ("a write by … in the thread …
landed while the erase of … ran; retry the erase, which clears that thread too"); the
person stays marked as being erased, and a retry finishes the erase and clears that thread
too.

A send still going out to the person when it is erased is forgotten with it, as for a
[forgotten thread](#forgetting-a-thread).

The person id rides the **path** — it is a uuid4 with no percent-encoded principal, so unlike
a thread id it round-trips a path segment cleanly. Authority is the door's **write** action —
the **same conversations write grant that forgets a thread**.

Erasing is **idempotent and retryable**. The person row is the durable marker of an owed
erase and is deleted **last** (atomically with its index mappings), so an interruption
re-reads it and a retry finishes. A person that is **already gone** — a retry, or one that
never existed — is not a `404`: its aggregated checkpoint is forgotten regardless (it defaults
to keep-forever) and the call answers `erased: false`.

A quote's text lives only on the records the erase deletes, so it is forgotten with them.
A parked ask in an erased thread is withdrawn before any record is deleted, so no
continuation runs with a quote; a synchronous ask still waiting reads `not_found` for a
quote into an erased thread.

The answer is `{person_id, removed, states_erased, erased, absorbed_person_ids}`, where `removed` counts the answer
records deleted across the person's routes, `states_erased` counts the declared-state records
this call forgot — the person's own (`person`-subject) and its aggregated thread's
(`thread`-subject) memory — and `erased` says whether **this** call removed the person
row. `removed` and `states_erased` also count what the erase cleared for the persons it
absorbed, and `absorbed_person_ids` lists their ids. A turn in flight in one of their
threads is a `409` like one in the person's own thread, and nothing of the person itself is
removed then.

Refusals: a turn in flight on the aggregated thread is a `409` (re-checked under the
per-thread FIFO before any teardown, so an admitted turn cannot re-create memory behind the
erase; a full queue is the retriable `503`); an id a `/link` absorbed into another person is
a `409` naming the person it was absorbed into, in its message and in
`absorbed_into_person_id` — that person's erase is the one that clears it, and it removes
that person too; the refusal touches nothing; a blank `person_id` is a `400`; no backend is
a loud `501`.

**While a person is being erased.** Once the erase has started, nothing new enters the
person's thread. A message sent to or from one of the person's addresses during the erase
goes to that address's own thread on its route, as after the erase. When the erase clears
that thread, a message landing in it before the erase reaches it is cleared with it, and one
after starts a fresh thread. A message already on its way to the person thread is not
recorded there: a send's record is forgotten with a WARNING; an inbound is refused with a
retriable `503` (or an error to the channel) and lands in the address's own thread when sent
again.

Meanwhile every read of the person answers as if it were gone (the person read and its
thread are `404`s). A link, an unlink or a locale change changes nothing and is refused
with a retriable `503`. A `/link`, a pairing code or an `/unlink` sent from one of the
person's own addresses reads the route's error text (`reply_texts.error`, by default "Sorry,
something went wrong handling your message. Please try again."), and its code stays valid.
A code the person minted, redeemed from another person's conversation, reads the
link-unavailable reply (`reply_texts.pairing_link_unavailable`) and is used up. A message
from one of its addresses is answered with the route's error text; sent again after the
erase, it starts as a new person in that address's own thread on its route (a fresh thread
when the erase cleared it). No declared state can be written for the person; a write already
under way when the erase starts is finished and then forgotten with the rest. Nothing
written for the person outlives the erase, and no other person's addresses or state are
touched.

An erase that stopped part way leaves the person treated as unlinked until it is run again,
which finishes it.

> [!NOTE]
>
> The erase covers the **bridge's** stores only. The person's run traces live in the
> monitoring backend, attributed by a `user_id` that is the `person_id` (or the raw
> address for an unlinked subject) — deleting them there is [your
> duty](/operate/observe#the-identity-dimensions), keyed on that same id. The traces of a
> person the erased person absorbed by a link carry that person's own id as their `user_id`,
> and the answer's `absorbed_person_ids` lists those ids, so delete the traces keyed on the
> erased id and on each listed id. The interaction store is not erased either: an answered
> question keeps the request's `recipient`, and a non-sensitive answer, until its idle TTL
> (`INTERACTIONS_IDLE_TTL_SECONDS`). Nor is the hooks store: a [hook run held as
> failed](/concepts/hooks#kept-and-retried) is kept with no TTL until an operator retries
> or discards it, and its event payload can carry the person's address. Discard such
> runs with `tai hooks runs discard`.

## Operator messages and control mode

Three thread-scoped operator doors govern how a thread is answered: one sends an
operator's reply by hand, two read and set the thread's **control mode**. All three
carry the [thread-belongs-to-route guard](#forgetting-a-thread) — a route-keyed id must
carry the route's `bridge:{route_name}:` prefix (`400` otherwise), and a person thread
must be on the named route (`404` otherwise).

| HTTP | CLI | Grant |
| - | - | - |
| `POST /api/conversations/{route_name}/thread/messages` | `tai conversations send <route> <thread> --text …` | **Write**. |
| `GET /api/conversations/{route_name}/thread/mode?thread_id=` | `tai conversations mode-get <route> <thread>` | **Read**. |
| `PUT /api/conversations/{route_name}/thread/mode` | `tai conversations mode-set <route> <thread> <mode>` | **Write**. |

The two write doors share the **same write grant that creates a route**, deletes
routes, and forgets threads — no per-thread owner check.

### Control mode

A thread runs in one of two control modes. **`agent`** (the route default) runs the
target turn — the agent run or the tool dispatch — on each inbound message. **`manual`**
**suppresses** the target turn so an operator answers by hand; the platform's own
control turns (pairing, the first-contact greeting) still run. The mode in force for a
thread is its per-thread override when one is set, else the route default: the route's
`initial_mode` for a route-keyed thread, and for a linked person's aggregated thread
`manual` when **any** route the person spans sets `initial_mode: manual`, else `agent`.

`manual` is valid on **every** target and door — `initial_mode`, the `PUT …/thread/mode`
door, and the `set_conversation_mode` builtin all take it, on a `tool` target or an agent
alike.

A `manual`-mode ordinary inbound is answered by nobody automatically: its target turn is
suppressed, so on a `channel` route the record ends terminal `silent` and on an `api`
route the silence is delivered as a `status: "silent"` marker. A pairing action and a
first-contact greeting are the exception — when a greeting is due it is prepended onto
the otherwise-silent outcome, so **that** record ends `answered`/`delivered` carrying the
greeting text. A greeting owed on a turn that is then superseded — cancelled by a newer
message or yielded by the turn body — is never dropped: it is carried to the successor turn
and leads that turn's reply, on every door.

Whether the suppressed inbound is **remembered** turns on the target's memory. A target
that keeps thread memory — an agent that implements the thread-memory append — has the
inbound appended to that memory, so a later `agent`-mode turn reads it as prior context;
an append that fails is a loud `error` outcome, never a silent drop. A target with no
thread memory — a `tool` target, or an agent that does not implement the append — skips
the step: the transcript is the record, and nothing is lost because such a target never
had a memory to fall out of. The same conditional append governs an
[operator send](#operator-send).

**Read** — `GET …/thread/mode?thread_id=` returns `{mode, source}`: `source` is
`thread` when a per-thread override is set, `route` when the answer is the route's
`initial_mode` default. The thread id rides the query string, as the transcript door
takes it.

**Set** — `PUT …/thread/mode` takes `{thread_id, mode}` (`mode` one of `agent`/`manual`)
and returns `{route_name, thread_id, mode, source}` with `source` always `thread` — a
set writes an override. This is the door an **external** or programmatic caller names a
thread through; an agent flipping its **own** live conversation uses the
`set_conversation_mode` builtin instead, which reads the current thread from the turn
context rather than naming it. The override carries the answer
records' `answer_retention_ttl_seconds` and is **refreshed on thread activity** — each
accepted inbound and each operator send — so it expires *with* the conversation: a
thread quiet past the retention window loses its override along with its records, and a
returning address starts again at the route default. A thread delete or a route delete
reclaims it at once.

Refusals (both mode doors): an unknown route `404`, a blank `thread_id` `400`, a
route-keyed id off the route `400`, a person thread off the named route `404`; `set`
adds a `400` for a `mode` outside `agent`/`manual`. Neither mode door takes an address.

### Operator send

`POST …/thread/messages` sends an operator's message **by hand** into a thread. Body:
`{thread_id, text, address?, media?, template?, options?, schema?}`; the answer is
`{message_id, thread_id}`. No turn runs: the record is minted already `answered` and
delivered through the same machine a produced answer takes — sent **from the route
identity**, with the same chunking, delivery ledger, and receipts. It is allowed in
**either** mode and **never flips the mode**.

`media`, `template`, `options`, and `schema` (an
[ask-less form](/concepts/notifications#ask-less-forms)'s answer schema — the channel
renders `text` as the form's prompt, and the participant's submission enters the
conversation as an ordinary inbound message) are optional richer-send forms delivered
**alongside** `text`: the message is stored and delivered as one rich part, exactly
as a produced rich answer is, including the delivery machine's capability gate — a
channel that does not advertise the matching `supports_*_notifications` flag never
receives the part; the record fails loudly instead of the field dropping. `options`
are the [typed reply/link shapes](/concepts/notifications#media-kinds-and-typed-options)
(a bare string is not an option); `template` carries its **named components**
(`header_media`, `body_parameters`, `buttons`). A contract-invalid value (an empty
list or dict, an over-cap value, or the mutually exclusive media+template /
options+template / schema+template / schema+options) is a loud `400`; omit all four
for a plain text send.

The record is `origin: "operator"`: it carries the text as its `answer`, an empty
`inbound_text`, never an `inbound_form` (an operator answers, it does not submit),
and names the sending operator in `caller_principal`. For a target that
**keeps thread memory** the text is appended to the thread's checkpoint as an `assistant`
reply **before** the record is created — the same [conditional append](#control-mode) a
suppressed inbound takes, mirroring how the agent's own answer enters memory — so a later
agent turn reads it as prior context; a target with no thread memory skips it. An append
that fails is a loud `500` and **no record is created**,
so the reply never stands in the transcript while absent from the memory a later turn
reads. The whole append-then-create runs under the thread's **per-thread FIFO** — the
same lock in-flight turns take — so the send waits behind an in-flight turn on that
thread and never interleaves its writes; a full queue is a loud, retriable `503`.

`address` picks the send target on a **linked person's** aggregated thread: it must be
one of the person's addresses (`400` otherwise), and its route is the named route when
the address wrote under it, else that address's own first route. With no `address` the
target is the thread's **newest record that is not a send record** — its route and client
address — so the reply returns where the person last wrote from (or where an operator last
sent); a person thread with no such record and no `address` is a `400`. On a route-keyed thread an explicit `address` must equal the address embedded in
the id.

Refusals: blank `text` `400`, a present-but-blank `address` `400`, the
thread-belongs-to-route guard's `400`/`404`, an unknown route `404`, a full thread queue
`503`, no backend `501`, and an **unauthenticated** caller `501` — an operator action
must be attributable, so access control must be enabled and the caller bound.

## The delivery lifecycle

An answer record moves through `accepted` → `pending_delivery` → `provisional` →
`delivered`, or ends `failed` (undelivered past the attempt budget, or reported
failed by the provider), `shed` (refused by the address rate cap; no turn ran), or
`silent` (nothing sent back for the inbound: a **channel** `tool` turn whose mapped
reply was `null`/blank, or an ordinary inbound on a `manual`-mode thread whose suppressed
target turn produced no reply). An **api** turn that resolves silent does **not** end
`silent`: it rides the delivery pipeline like any answer and ends `delivered`, its
callback carrying `status: "silent"`. A message handed to another turn under an
[overlap policy](#overlapping-messages) ends `merged` (its text carried into the named turn) or
`superseded` (dropped in favour of one) — both answerless terminal outcomes naming that turn in
`successor_id`, and on the **api** door delivered as a marker exactly as `silent` is. Only the
terminal states (`delivered`, `failed`, `shed`, `silent`, `merged`, `superseded`) carry the
retention TTL.
Delivery is retried with exponential backoff; a provisional record awaits an
out-of-band receipt until `delivery_grace_seconds` elapses. A restart re-drives
every unfinished record, delivering exactly once (no double callback).

A **send record** has its own path. It is written `sending` before the message goes out,
then moves to `provisional` when the medium accepts it (and on to `delivered` by a
receipt or the grace period, as an answer does), `failed` when the send raised, or
`outcome_unknown` when nobody can tell whether the message went out: the send passed its
bound, it was cancelled while the medium call was in flight, an ask attempt timed out and
no later one succeeded, or the process stopped after the `sending` write. A send record is
**never re-sent**: an `outcome_unknown` record keeps its `error`, a WARNING names it (the
texts are in [Send outcomes and delivery receipts](/operate/observe#send-outcomes-and-delivery-receipts)),
and a send that passed its bound raises a non-retryable error, so no caller retry sends it
twice. A `sending` row the process left behind is settled to `outcome_unknown` by the sweep
or the boot redrive once its settle deadline passes. An ask whose attempt timed out before a
later attempt succeeded completes from the later attempt, with `ask.timed_out_attempts`
naming the earlier ones and a WARNING that the participant may have received the question
more than once. A reply over the channel moves an ask's record to `delivered`, whatever its
delivery state was. `sends` holds one entry per part the medium accepted.

The write comes first: a send whose `sending` write fails is not made, and the store error
is raised (a platform notice logs it at ERROR instead). A send the medium accepted whose
completion write then fails is logged at ERROR with its message ids and returned to the
caller, never raised, so it is not sent twice; its row is later settled as
`outcome_unknown`.

**A receipt that arrives before the send finishes is held, not lost.** A channel can deliver a
delivery receipt (a status callback) for an outbound message before the platform has finished
recording that send. When it does, the receipt is **parked** on the record — the callback is
acknowledged normally, so the provider does not redeliver in a loop — and applied the moment
the send completes, moving the record straight to its `delivered` or `failed` outcome. If the
send itself reaches a failure terminal first, the sender's verdict wins and the parked receipt
is dropped with a logged warning. An in-flight record holding a receipt shows it in the admin
record view under `pending_receipt`.

When a reachable channel terminally refuses a turn's reply — an answer over the
channel's cap, an unrenderable part, a permanent input refusal, or a non-retryable
send rejection — the record stays `failed` and the participant is sent the platform's
fixed could-not-deliver notice (the route's `reply_texts.error` when set, else
the built-in default); a transport exhaustion — retryable failures that spend
every attempt — stays `failed` with no such notice, the failed-delivery listing being
the only signal.

A pending or provisional delivery row that can never be parsed is moved to the terminal
`failed` state — it stops being retried on every sweep and appears on the failed-delivery
listing, where an operator can see and clear it. For those delivery-lifecycle rows the
`unreadable` count a listing reports and this terminal `failed` state are the same fact seen
twice: the row a read tallies as `unreadable` is the row the sweep fails, not a second one. A
corrupt row counted `unreadable` on any other listing (a thread, transcript, route, or config
listing) has no `failed` twin — the sweep only transitions delivery-lifecycle rows, so those
counts stand on their own.

### Failure replies

The platform never puts an internal detail into the text a participant reads. Its own
failure text is fixed and client-safe; a target that fails may supply a reply of its own,
and the platform sends that reply exactly as the target wrote it.

* **Turn error** — when a turn fails, the participant reads the first of:

  1. the **target's reply**, when its failure carries one;
  2. the route's own `reply_texts.error` (set with `--reply-error`);
  3. the built-in default `"Sorry, something went wrong handling your message. Please
     try again."`

  On a live turn the internal detail is kept in the record's `error` field, for the
  admin read door only. A failure delivered when a parked run resumes keeps no `error`
  detail on its record.
* **Rate-cap slow-down** — `"You are sending messages faster than I can answer.
  Please wait a moment and try again."` — or the route's `reply_texts.slow_down` when set —
  sent once per cooldown window; further
  over-limit messages are dropped as `shed`.

A target supplies its reply on the failure it reports. A tool raises
`RunTerminalFailed(outcome, reply="...")`; a parked run that fails on resume raises the
same, or returns `RunFailed(outcome=..., reply="...")`. A flow supplies one through its
flow-level On Error's [Reply](/babelfish#the-participant-reply-on-a-failed-run). The reply follows the same rule as
every `reply_texts` member: a string of 1 to 2,000 characters that is not blank. An invalid reply
is refused where the target raises or returns it, and a reply that reaches a completion
delivery malformed is refused loudly there, with no record written.

The target's reply covers only the target's own failure. Every failure the platform owns
keeps the fixed text above: an infrastructure error or any other exception raised in place
of a reported failure (a timeout among them), a door contract or `reply_expr` fault, a
denied run, a stranded turn, a channel refusal notice, and a give-up with no handler result.
A transport exhaustion sends no notice at all.

> [!WARNING]
>
> A target's reply is shown to the participant as written. Its author owns that it is safe
> for the participant and carries no internal detail, just as a route admin owns the
> route's `reply_texts`.

### The route's reply texts

A route may set its own words for every reply the platform sends on its own, in the line's
language. `reply_texts` is an optional object; each member is optional, and a member left unset
sends the built-in English text. An empty object, an unknown member, or a blank or over-long
member (each 1 to 2,000 characters) is refused at the route write.

| Member | Sent when | Built-in text | CLI flag |
| - | - | - | - |
| `error` | a turn fails and the target gave no reply | `Sorry, something went wrong handling your message. Please try again.` | `--reply-error` |
| `slow_down` | an address is over the turn rate | `You are sending messages faster than I can answer. Please wait a moment and try again.` | `--reply-slow-down` |
| `pairing_code` | the `/link` reply carrying a fresh code | `Your pairing code is <code>. Send it from your other conversation to link the two. It expires at <time>.` | `--reply-pairing-code` |
| `pairing_code_invalid` | a pairing code is refused | `That pairing code is not valid. It may have expired or already been used.` | `--reply-pairing-code-invalid` |
| `pairing_linked` | a code is redeemed and the two addresses are linked | `Done — this conversation is now linked to your other one.` | `--reply-pairing-linked` |
| `pairing_unlinked` | `/unlink` detaches the address | `Done — this conversation is no longer linked.` | `--reply-pairing-unlinked` |
| `pairing_not_linked` | `/unlink` comes from an address linked to nothing | `This conversation is not linked to anything, so there is nothing to unlink.` | `--reply-pairing-not-linked` |
| `pairing_link_unavailable` | a code is redeemed while a person it would link is being erased (the code is used up) | `This conversation can't be linked right now. Please try again in a moment with a new code: send /link in your other conversation.` | `--reply-pairing-link-unavailable` |
| `pairing_unlink_unavailable` | `/unlink` comes while the person is being erased | `This conversation can't be unlinked right now. Please try again in a moment.` | `--reply-pairing-unlink-unavailable` |
| `rejected_unsupported_type` | an inbound message the channel cannot carry | `This content type is not supported here.` | `--reply-rejected-unsupported-type` |
| `rejected_too_large` | an inbound file over the size cap | `That file is too large to accept here.` | `--reply-rejected-too-large` |
| `rejected_could_not_receive` | an inbound file the channel could not fetch | `That attachment could not be received.` | `--reply-rejected-could-not-receive` |

`pairing_code` is a template: it must contain `{pairing_code}` (the code) and may contain
`{expires_at}` (the code's ISO-8601 expiry), with no other field, conversion or format spec.
Every other member is literal text: a `{` in it is sent as written.

```bash theme={null}
tai conversations create chat-line --target-kind agent --target-name assistant \
  --door channel --channel web --identity assistant --execution-key <key> \
  --reply-error "Something broke on our side. Please try again." \
  --reply-pairing-code "Your code is {pairing_code}. It works until {expires_at}."
```

In the Studio the route dialog carries the same members as its **Reply texts** group; a field
left blank sends the built-in English reply.

![The Reply texts group of the route dialog, one input per reply, with Failed turn and Pairing code filled in and the rest blank.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/conversation-route-reply-texts-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=4dbfd8402ee20dffa9df02aa7334747f)

The route dialog's Reply texts group, with the failed-turn and pairing-code replies set.

## Checkpoint retention

Conversation continuity is the checkpoint store's. Thread expiry is governed by the LLM
checkpoint settings (the `LLM_PROVIDER_*` group), not a `CONVERSATIONS_*` setting:

| Setting | Env | Default |
| - | - | - |
| `checkpoint` | `LLM_PROVIDER_CHECKPOINT` | `redis` |
| `checkpoint_retention_waiting_minutes` | `LLM_PROVIDER_CHECKPOINT_RETENTION_WAITING_MINUTES` | `10080` (7 days) |

A conversation thread is never marked finished — it stays open for its next turn — so it
lives the waiting retention after its last write: a thread that keeps receiving messages
keeps living, and one that sits idle past the retention expires. A turn's agent that
checkpoints on the thread takes it out of the store's finished set when its run starts; an
agent that keeps no checkpoints touches no checkpoint store. How the window is enforced
depends on the provider:

* `redis` stamps every key a checkpoint write stores with the retention as its TTL, and a
  read never extends it — expiry is automatic.
* `postgres` / `sqlite` have no native expiry; the **sweep operation** deletes every thread
  whose newest checkpoint is older than the cutoff.
* `memory` is process-lifetime.

See [Checkpoints and retention](/operate/checkpoints) for both horizons, the threads other
owners mark finished, and the live-thread filters that spare a thread a parked run still
needs.

> [!NOTE]
>
> The `postgres` checkpoint and store tables are **self-managed by LangGraph**: the
> library creates and maintains its own schema. They are not part of a
> [migration chain](/concepts/marketplace#the-migrations-contract) and are outside
> `tai db migrate` / `tai db status`, which cover only the framework's and plugins'
> own tables. There is nothing to migrate here — LangGraph sets its tables up on
> first use.

### The sweep operation

`sweep_checkpoints` (`POST /api/checkpoints/sweep`, `tai checkpoints sweep`) is
**admin-tier** (a fenced, deployment-wide destructive memory purge). It deletes finished
threads past the finished retention on every provider and, on a DB-backed provider, every
thread past the waiting retention; a thread a live-thread filter claims (a live park) is
spared and listed. See [the checkpoint sweep](/operate/checkpoints#the-checkpoint-sweep) for
its result. It runs on either recurrence path:

* **Native schedules** — recurrence needs the tool branched with the backend's
  `schedule_task` extension: wrap the sweep in a small manifest tool carrying
  `schedule_task`, then schedule that branched tool via `POST /api/schedules`
  (`tai schedules …`) on a scheduler-capable backend. (Projecting as a tool makes
  the sweep runnable by name; the `schedule_task` branch is what registers a
  recurrence.)
* **External cron** — call `tai checkpoints sweep` on a timer from your own cron /
  systemd timer / k8s CronJob. The busless path — no scheduler backend needed.

## The fire-path authorization model

A conversation route separates *who may send* from *what the turn may do*, and both
are enforced live.

> [!WARNING]
>
> A `public` trigger-auth hook can be fired by **anyone, with no credential** — so the
> bound `execution_key` is the **only** thing bounding what a fired hook can do. Treat the
> key as the security boundary: bind a **least-privilege** key, and **never** bind an admin
> or broad key to a `public` (or `token`) hook — that lets any caller act with those
> privileges. Use `verifier` or `api_key` triggers when the fire itself must be
> authenticated.

**Who may send.** A `channel` message is authenticated by the provider's own
signature over the raw webhook body (fail-closed — a missing or bad signature is
rejected and runs no turn). An `api` message is authenticated by the access-control
gate on the send door. This mirrors the general
[trigger authentication](/concepts/triggers-and-webhooks) posture — a door is
public, verifier-signed, token-gated, or API-key-gated — applied to the two
conversation doors.

**What the turn may do.** The turn runs **as** the route's bound `execution_key`,
never as the sender. That key's **live** stored grants authorize the agent run (or
the `tool` target's dispatch) and every tool call the turn makes — including any tool
a deep-agent sub-agent calls. The rules:

* **Bind (pass-role).** You may bind your own identity or an execution key you own;
  an admin may bind any key. A non-admin's refusal is a uniform `403` across
  absent-key and not-yours, so the door is no probe for key ids.
* **Token-free-evaluable only.** The bound key's stored policy condition must be
  resolvable by a background execution with no request token. A condition that needs
  a request token is rejected at bind — it could never be evaluated at fire.
* **Fingerprint binding.** The route stores a server-derived per-mint
  `execution_key_fingerprint`. The fire resolves the identity against that
  fingerprint, so a key re-minted under a new fingerprint no longer satisfies the
  route until it is re-bound.
* **Enforce at fire, automatic revocation.** The turn is authorized against the
  key's grants at fire time, not at bind. Attenuate the key by any means — drop a
  scope, disable it, delete it, narrow its owner — and the next turn is denied, with
  no revocation-specific step on the route. Scope the key (and the agent) to least
  privilege.

A denied run does not crash the turn: it becomes a client-safe `error` outcome, its
detail retained for the admin read door.

**Signed-callback posture.** An `api` route's `callback_url` is optional; when set it
must be absolute **HTTPS** — an `http://` or relative URL is rejected at create, with
**no** insecure opt-out. A route with no `callback_url` records every answer for the poll
door (`GET /api/conversations/{route_name}/messages/{message_id}`) instead. Every callback
is signed: `X-Tai-Signature: sha256=<HMAC-SHA256(callback_secret,
raw_body)>`, over a body of `{message_id, thread_id, status, answer}` — with `answer`
absent on a `silent`, `merged`, or `superseded` outcome, and a `successor_id` present on
`merged`/`superseded` naming the turn that took the message's place. See [connect your own
system](/guides/connect-your-own-system#verify-the-x-tai-signature).

## Settings

Every setting reads the `CONVERSATIONS_` env prefix (so `max_concurrent_turns` is
`CONVERSATIONS_MAX_CONCURRENT_TURNS`). Startup validators reject an invalid
combination loudly. The `CONVERSATIONS_` prefix is owned: an env name under it that names no
setting below is refused at boot and on every env write.

### Backend

| Setting | Default | Meaning |
| - | - | - |
| `redis_url` | *(unset)* | `CONVERSATIONS_REDIS_URL`. No URL → no durable store → every routing op refuses `501`. |
| `redis.socket_connect_timeout` | `5` | Seconds; bounds the connect so a black-holed Redis fails loudly. |
| `redis.socket_timeout` | `5` | Seconds; bounds each command read. |
| `prefix` | `conversations` | Keyspace prefix for every conversation key. |

### Turn-engine bounds

| Setting | Default | Meaning |
| - | - | - |
| `max_concurrent_turns` | `10` | One semaphore bounds **total** in-flight turns on the worker. |
| `thread_queue_depth` | `20` | Per-thread FIFO depth; a message that would exceed it is refused (`503`). |
| `per_address_turns_per_hour` | `20` | Per-`client_address` token-bucket rate (turns per rolling hour). |
| `address_bucket_max_entries` | `50000` | Max per-address buckets one worker holds; a flood evicts rather than growing unbounded. |
| `sync_wait_max_seconds` | `120` | Upper clamp on the API door's `wait_seconds` before it falls back to `202`. |
| `intake_claim_lease_seconds` | `120` | Seconds a running turn's intake lease stays live; only a lapsed lease is re-driven. |
| `intake_claim_refresh_seconds` | `30` | Intake-lease refresh interval; must stay **below** the lease. |
| `thread_lease_seconds` | `120` | Seconds a running turn's cross-worker thread lease stays live; only on expiry (a crashed holder) may another worker take the thread. |
| `thread_lease_refresh_seconds` | `30` | Thread-lease refresh interval; must stay below the lease. |
| `overlap_cancel_poll_seconds` | `0.5` | Seconds the [overlap-cancel](#overlapping-messages) watcher sleeps between reads of a thread's cancel marker while a `running: cancel` turn runs; must stay **below** `thread_lease_seconds`. |
| `sync_door_wait_seconds` | `30` | Seconds a synchronous door — operator send / thread or person delete — waits to serialize behind an in-flight turn before answering a retriable 503. |
| `working_signal_max_seconds` | `180` | Hard ceiling in seconds on one turn's [working-on-it](#the-working-on-it-signal) refresh loop; `0` disables the loop entirely (the kill switch). |
| `working_signal_refresh_margin_seconds` | `5` | Seconds subtracted from a channel's vendor-indicator lifetime to pick the refresh interval, so each refresh lands before the indicator lapses. |

A turn waiting for a busy thread starts when the running turn releases the thread (a
notification), or when a crashed holder's lease expires.

The notification is Redis pub/sub on the conversations Redis: a release publishes the thread id
on the channel `<prefix>:thread_lease_released`, and a waiting turn subscribes to it. When the
conversations Redis user is a restricted ACL user (Redis 7 creates new ACL users with
`resetchannels`), grant it the `PUBLISH` and `SUBSCRIBE` commands and that channel (for example
`+publish +subscribe &conversations:thread_lease_released` with the default `prefix`). Without
them every release logs `conversations: releasing thread lease … failed; its TTL is the hard
bound` and every turn that has to wait for a busy thread fails on its subscribe.

### Delivery bounds

| Setting | Default | Meaning |
| - | - | - |
| `delivery_max_attempts` | `8` | Attempts before an undelivered answer is marked `failed` (retained). |
| `delivery_backoff_base_seconds` | `60` | First retry wait; each later one doubles. |
| `delivery_backoff_max_seconds` | `900` | Backoff ceiling. |
| `delivery_claim_lease_seconds` | `120` | Seconds a delivery worker's exactly-once claim stays live. |
| `delivery_send_timeout_seconds` | `60` | Bounds one outbound channel send — a bridge reply's part, a `notify_user` send, a platform notice, a channel plugin's recorded send; must stay **below** the delivery lease. |
| `delivery_callback_timeout_seconds` | `15` | Bounds one api-door callback POST; must stay **below** the delivery lease. |
| `delivery_sweep_interval_seconds` | `60` | Seconds between stalled-delivery sweep passes. |
| `delivery_grace_seconds` | `3600` | Seconds a `provisional` record waits for a receipt before it confirms `delivered`. |
| `max_message_chars` | `{twilio: 1600, telegram: 4096, slack: 40000, whatsapp: 4096}` | Per-channel outbound split caps. A routed channel absent from the map is a loud config error at send. |
| `max_outbound_chunks` | `10` | Max provider messages one answer may fan out to; a longer answer is refused with a client-safe error, never silently truncated. |

A send record's **settle deadline** is the time it was begun, plus the send's bound
(`delivery_send_timeout_seconds`, or for an ask what is left of its window), plus
`delivery_claim_lease_seconds`. A row still `sending` past it is settled to
`outcome_unknown` within `delivery_sweep_interval_seconds`.

### Retention / idempotency

| Setting | Default | Meaning |
| - | - | - |
| `inbound_dedupe_ttl_seconds` | `172800` (48h) | How long a seen `(channel, provider_message_id)` stays deduped; a replay within it starts no second turn. |
| `answer_retention_ttl_seconds` | `2592000` (30d) | Applied to a record, its indexes and its message-refs **only** on the terminal transition; before that it carries no expiry. |

**Message-refs.** Each record also keeps a message-ref per medium message it carries,
`conversations:message_ref:{sha256}`, keyed on the channel, the route identity, the
participant address and the medium's own message id. It maps that id to the ordered list
of records that carry it: one medium message can be several records (a Slack message with
several files, or a Twilio message with several media items, is one record per item, all
under the same id). This is how a quote of a message resolves to its record.

An inbound record keeps two ids. The dedupe id (`provider_message_id`) is what makes a
replay start no second turn, and can be per item (`{event_id}-{index}` on Slack,
`{MessageSid}-{index}` on Twilio). `medium_message_id` is the medium's own id for the
message itself, the one a later quote names; each channel's [plugin page](/plugins) says
which id it passes.

## See also

* [Client conversations](/concepts/client-conversations) — the model.
* [WhatsApp](/guides/whatsapp-to-agent), [Telegram / Slack](/guides/telegram-slack-to-agent),
  and [your own system](/guides/connect-your-own-system) — the setup guides.
* [Access control](/concepts/access-control) and [owned keys](/concepts/owned-keys)
  — the execution key's grants.


# Accounts (tai42_contract.accounts)
Source: https://docs.tai42.ai/reference/python-sdk/contract-accounts

The AccountsProvider contract and the login-method metadata models.

The accounts provider contract: user accounts, login flows, sessions.

## AccountsAdminServices

`tai42_contract.accounts.provider.AccountsAdminServices`

```python theme={null}
class AccountsAdminServices(Protocol)
```

Application-side policy services an accounts provider may invoke.

Implemented by the application and INJECTED via
`AccountsProviderSettings.admin` — accounts plugins never import the
application package, so this Protocol is the only way plugin code can
create a principal, apply a role template, remove a principal's policy,
or flip the disabled marker. Every method mutates application-owned
principal and policy state; the plugin never touches that state directly.

### Members

#### create\_principal

`tai42_contract.accounts.provider.AccountsAdminServices.create_principal`

```python theme={null}
async create_principal(
    self,
    user_id: str,
    *,
    kind: PrincipalKind,
    display_name: str,
    created_by: str | None,
    role: str,
) -> None
```

Create the principal row and apply its role.

A `human` principal authenticates through an accounts provider; a
`service` principal holds keys only. `created_by` is the principal
id that created this one, or `None` for the setup door. Raises loudly
if the principal already exists or the role is unknown.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `user_id` | `str` | — | — |
| `kind` | `PrincipalKind` | — | — |
| `display_name` | `str` | — | — |
| `created_by` | `str \| None` | — | — |
| `role` | `str` | — | — |

#### apply\_role

`tai42_contract.accounts.provider.AccountsAdminServices.apply_role`

```python theme={null}
async apply_role(self, user_id: str, role: str) -> None
```

Copy the named role template into the principal's enforced policy.

Guarded: raises `LastAdminError` (nothing
written) when the principal is the last enabled admin and `role` is not an
allow-all role. Raises `KeyError` on an unknown role.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `user_id` | `str` | — | — |
| `role` | `str` | — | — |

#### remove\_policy

`tai42_contract.accounts.provider.AccountsAdminServices.remove_policy`

```python theme={null}
async remove_policy(self, user_id: str) -> None
```

Delete the principal's enforced policy and row (and revoke keys it owned).

Guarded: raises `LastAdminError` (nothing
written) when the principal is the last enabled admin. Raises `KeyError` when the
principal or its policy is absent.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `user_id` | `str` | — | — |

#### set\_user\_disabled

`tai42_contract.accounts.provider.AccountsAdminServices.set_user_disabled`

```python theme={null}
async set_user_disabled(self, user_id: str, disabled: bool) -> None
```

Set/clear the disabled marker on the principal.

Guarded for `disabled=True`: raises
`LastAdminError` (nothing written) when the
principal is the last enabled admin. Raises `KeyError` when no principal exists.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `user_id` | `str` | — | — |
| `disabled` | `bool` | — | — |

#### principal\_roles

`tai42_contract.accounts.provider.AccountsAdminServices.principal_roles`

```python theme={null}
async principal_roles(self, user_ids: Sequence[str]) -> Mapping[str, str | None]
```

The role each principal holds.

The reserved admin role name when its own policy is admin-shaped, else its role
pointer, else `None` (a policy not written from a role template). A user id with no
principal is absent from the mapping.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `user_ids` | `Sequence[str]` | — | — |

## AccountsProvider

`tai42_contract.accounts.provider.AccountsProvider`

```python theme={null}
class AccountsProvider(IdentityProvider)
```

A user-accounts provider: login methods plus session-token validation.

An accounts provider owns human accounts and the login flows that mint
session tokens for them. It IS an identity provider: the session tokens
it mints are validated through the inherited `validate_token` — the
same seam every credential passes through — so installing an accounts
provider never adds a second enforcement pathway.

Session tokens are opaque strings minted and stored by the provider
(recommended prefix `tai-sess-` to distinguish them from `sk-` API
keys at a glance); the contract never parses token contents. Storage,
hashing, and lifetime are provider-owned.

Login/lifecycle HTTP routes (submit endpoints, redirect flows) are
shipped by the provider plugin as ordinary router modules; the contract
carries only the metadata that lets a generic login screen render them.

### Members

#### login\_methods

`tai42_contract.accounts.provider.AccountsProvider.login_methods`

```python theme={null}
login_methods(self) -> list[LoginMethod]
```

Declare the login methods this provider offers.

Called by the application's public login-methods aggregator. Must be
cheap and side-effect free: this is static, config-derived metadata,
not I/O (sync by contract, like `readiness_targets`).

#### list\_members

`tai42_contract.accounts.provider.AccountsProvider.list_members`

```python theme={null}
async list_members(self) -> MemberListing
```

List the people this provider owns and the invitations it holds.

Called by the application's Members aggregator, which concatenates one
`MemberListing` per registered accounts
provider into a single deployment-wide view. Each person is a
`MemberEntry` and each outstanding
invitation an `InviteEntry`; how a
provider partitions its accounts between the two lists is its own concern. Reads
the provider's own store, so this is I/O (async). Backend errors raise (the
aggregate fails loudly rather than dropping a provider's accounts silently).

#### member\_actions

`tai42_contract.accounts.provider.AccountsProvider.member_actions`

```python theme={null}
member_actions(self) -> list[MemberAction]
```

Declare this provider's member-admin actions.

Static, config-derived metadata, side-effect free (sync by contract, like
`login_methods`). Each `MemberAction`
names the action's own id, its label (by template id), where it renders, whether
it is destructive, and its input/result models. WHICH of these apply to a given
row is a separate, state-dependent decision reported per row by `list_members`
(see `actions`). A provider with
no actions returns `[]`.

#### invoke\_member\_action

`tai42_contract.accounts.provider.AccountsProvider.invoke_member_action`

```python theme={null}
async invoke_member_action(self, action_id: str, *, target: str | None, payload: BaseModel) -> BaseModel
```

Perform the action named by this provider's own `action_id`.

`target` is the provider's stable id of the member/invite row the action acts on
(`None` for a page-scoped action). `payload` is the already-validated instance
of the action's declared `input_model`. Returns an instance of the action's
declared `result_model`, which the platform carries opaquely (it reads no field
of it). A correctable failure is raised as a member-action error from
`tai42_contract.accounts.errors` — `MemberActionError`
for a rejected input, `MemberActionNotFoundError`
for an unknown target, `MemberActionConflictError`
for a state conflict, `MemberActionBadRequestError`
for a malformed request — so the invoke operation maps it to the matching status
without the provider importing the application package.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `action_id` | `str` | — | — |
| `target` | `str \| None` | — | — |
| `payload` | `BaseModel` | — | — |

#### revoke\_session

`tai42_contract.accounts.provider.AccountsProvider.revoke_session`

```python theme={null}
async revoke_session(self, token: str) -> bool
```

Revoke the session behind `token` if it is this provider's.

Returns `True` when a session was found and revoked; `False`
when the token is not this provider's (wrong prefix, unknown). The
application's single logout route dispatches across ALL registered
accounts providers, so implementations must answer `False` for
foreign tokens instead of raising. Backend errors still raise
(fail closed).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `token` | `str` | — | — |

## AccountsProviderSettings

`tai42_contract.accounts.provider.AccountsProviderSettings`

```python theme={null}
class AccountsProviderSettings(Protocol)
```

Settings shape handed to an accounts-provider factory.

`admin` is typed loosely (`Any`) because the contract cannot name the
application's `AccountsAdminServices` implementation class; it carries that
implementation. A provider reads its OWN backing-store handles and key
namespaces from its own settings, never off this object, so the contract names
no store-specific field here.

**Attributes**

| Attribute | Type |
| - | - |
| `admin` | `Any` |

## LoginAttachingProvider

`tai42_contract.accounts.provider.LoginAttachingProvider`

```python theme={null}
class LoginAttachingProvider(LoginOwningProvider)
```

An accounts provider that holds an interactive credential it can set for a principal.

A provider mixes this in when it owns an interactive credential it can attach to a
principal (a password, or a one-time invite link). The setup door and the login-methods
door `isinstance`-check for it: a provider whose login lives at an external issuer
does not implement it, and the caller reports the login as not attached.

The credential's own disabled state lives with the provider, so the principals door also
routes a DISABLE of a principal it claims (`has_login`) to the
provider's member actions, never the principals door.

### Members

#### attach\_login

`tai42_contract.accounts.provider.LoginAttachingProvider.attach_login`

```python theme={null}
async attach_login(self, user_id: str, *, credential: LoginCredential) -> LoginAttachment
```

Attach `credential` to the existing principal `user_id`.

A `PasswordCredential` sets the
password now; an `InviteCredential`
mints a one-time link returned on the `LoginAttachment`.
A correctable-input failure (a too-short password) raises
`LoginAttachError`; a login already
existing for the principal or a taken email raises
`LoginConflictError`. The state is
unchanged on either, so the caller surfaces the failure and stays retriable.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `user_id` | `str` | — | — |
| `credential` | `LoginCredential` | — | — |

## LoginOwningProvider

`tai42_contract.accounts.provider.LoginOwningProvider`

```python theme={null}
class LoginOwningProvider(AccountsProvider)
```

An accounts provider that keeps a login record for principals.

A provider mixes this in when it keeps its own record of a principal's login — a record
that must never outlive the principal. The principals door asks every registered owning
provider `has_login` before it DELETES a principal: a principal some provider claims
is removed through that provider's member actions, which remove the principal and the
record together, never through the principals door.

### Members

#### has\_login

`tai42_contract.accounts.provider.LoginOwningProvider.has_login`

```python theme={null}
async has_login(self, user_id: str) -> bool
```

Whether this provider keeps a login record for the principal `user_id`.

The principals door reads this before a delete: a `True` means the provider's
member actions remove the principal; a `False` means the provider keeps nothing for
it (a service principal, a principal provisioned by hand, the keys-only owner), and
the principals door removes it directly. A backend error raises (fail closed), never a
silent `False`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `user_id` | `str` | — | — |

Data models for the accounts plugin kind.

An accounts provider declares HOW a human can sign in as data; the Studio
login shell renders that data. Exactly two login-method shapes exist: a
credentials form posted to a provider route, and a button linking to a provider
redirect flow. The provider supplies every piece of content (titles, labels,
icons, paths); the renderer supplies only the two shapes.

The same module carries the credential shapes a provider attaches to a principal
and the membership shapes it lists — the people it owns and the invitations it
holds — so a generic Members view can render every provider's accounts without
naming any of them.

## ButtonMethod

`tai42_contract.accounts.models.ButtonMethod`

```python theme={null}
class ButtonMethod(BaseModel)
```

A redirect button: the renderer draws a button that navigates to href (e.g. an OIDC authorize route).

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `shape` | `Literal['button']` |
| `id` | `str` |
| `label` | `str` |
| `icon` | `str \| None` |
| `href` | `str` |

## FormField

`tai42_contract.accounts.models.FormField`

```python theme={null}
class FormField(BaseModel)
```

One input of a form-shaped login method.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `name` | `str` |
| `label` | `str` |
| `secret` | `bool` |
| `autocomplete` | `str \| None` |

## FormMethod

`tai42_contract.accounts.models.FormMethod`

```python theme={null}
class FormMethod(BaseModel)
```

A credentials form: the renderer draws the fields and POSTs them as JSON to submit\_path.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `shape` | `Literal['form']` |
| `id` | `str` |
| `title` | `str` |
| `purpose` | `Literal['login', 'invite']` |
| `fields` | `list[FormField]` |
| `submit_path` | `str` |

## InviteCredential

`tai42_contract.accounts.models.InviteCredential`

```python theme={null}
class InviteCredential(BaseModel)
```

A login credential that mints a one-time invite link instead of setting a password now.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `kind` | `Literal['invite']` |
| `email` | `str` |

## InviteEntry

`tai42_contract.accounts.models.InviteEntry`

```python theme={null}
class InviteEntry(BaseModel)
```

One outstanding invitation an accounts provider holds.

`id` is the provider's stable handle for the invited person — the id its own actions
act on. `email` is the invited address; `role` names the platform role the person
will hold (only the name — the role's definition is read from the role listing; `None`
— the policy is not written from a role template). `created_at` and
`expires_at` are timezone-aware (UTC). `actions` are the provider's OWN
member-action ids applicable to this row. An invitation holds no principal yet, so it
carries no `principal_ids`.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `id` | `str` |
| `email` | `str` |
| `role` | `_RoleName` |
| `created_at` | `datetime` |
| `expires_at` | `datetime` |
| `actions` | `list[str]` |

## InviteRow

`tai42_contract.accounts.models.InviteRow`

```python theme={null}
class InviteRow(BaseModel)
```

An invite row in the aggregated directory the Members door returns.

Display fields plus the opaque routing tokens. An invitation holds no principal, so it
carries no principal state, and `role` is provider-sourced; `None` — the policy is
not written from a role template.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `id` | `str` |
| `email` | `str` |
| `role` | `_RoleName` |
| `created_at` | `datetime` |
| `expires_at` | `datetime` |
| `handle` | `str` |
| `action_keys` | `list[str]` |

## InvokeMemberActionRequest

`tai42_contract.accounts.models.InvokeMemberActionRequest`

```python theme={null}
class InvokeMemberActionRequest(BaseModel)
```

The invoke-door envelope: which action, which row, and the per-action input.

`action_key` is the opaque catalog key; `target_handle` is the row handle an
action acts on (`None` for a page-scoped action); `input` is an open mapping the
operation hands to the declared `input_model` for ordinary validation, so the
platform's static envelope never needs to know the per-action fields. Unknown
top-level keys are ignored (pydantic's default extra behaviour).

**Attributes**

| Attribute | Type |
| - | - |
| `action_key` | `str` |
| `target_handle` | `str \| None` |
| `input` | `dict[str, Any]` |

## InvokeMemberActionResult

`tai42_contract.accounts.models.InvokeMemberActionResult`

```python theme={null}
class InvokeMemberActionResult(BaseModel)
```

The invoke-door result: the provider's result-model dump, carried opaquely.

`result` is the `model_dump(mode="json")` of the action's declared
`result_model` instance; the platform reads no field of it.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `result` | `dict[str, Any]` |

## LoginAttachment

`tai42_contract.accounts.models.LoginAttachment`

```python theme={null}
class LoginAttachment(BaseModel)
```

The outcome of attaching a login to a principal.

`attached` is whether an interactive login was attached. `invite_token`
and `login_path` are set only for an invite credential — the one-time link
the operator follows to set the password later.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `attached` | `bool` |
| `invite_token` | `str \| None` |
| `login_path` | `str \| None` |

## LoginCredential

`tai42_contract.accounts.models.LoginCredential`

```python theme={null}
LoginCredential = Annotated[PasswordCredential | InviteCredential, Field(discriminator='kind')]
```

The closed union of login credentials a provider can attach to a principal.

## LoginCredentialKind

`tai42_contract.accounts.models.LoginCredentialKind`

```python theme={null}
LoginCredentialKind = Literal['password', 'invite']
```

The `kind` tags of `LoginCredential`, one per credential variant.

## LoginMethod

`tai42_contract.accounts.models.LoginMethod`

```python theme={null}
LoginMethod = Annotated[FormMethod | ButtonMethod, Field(discriminator='shape')]
```

The closed union of renderable login-method shapes.

## MemberAction

`tai42_contract.accounts.models.MemberAction`

```python theme={null}
class MemberAction(BaseModel)
```

One member-admin action an accounts provider declares.

An IN-PROCESS declaration returned by
`member_actions`. The
platform serializes a wire `MemberActionDescriptor` from it and validates an
invoke's input by calling `input_model.model_validate(input)` (plain pydantic).
`input_model` and `result_model` are OPAQUE to the platform: it reads no field of
either, it only renders their JSON schema and runs the ordinary model validation and
dump. `id` is the provider's OWN action id — the platform maps it to an opaque wire
key and never parses or branches on it. `label` is a `TemplatedText`
reference (a stored template id or inline content), so the wording is localizable
through the platform's existing resource manager and never held as a literal here.

Not serialized to the wire (it carries class references), so
`arbitrary_types_allowed` is safe.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `id` | `str` |
| `label` | `TemplatedText` |
| `scope` | `MemberActionScope` |
| `destructive` | `bool` |
| `input_model` | `type[BaseModel]` |
| `result_model` | `type[BaseModel]` |

## MemberActionCatalog

`tai42_contract.accounts.models.MemberActionCatalog`

```python theme={null}
class MemberActionCatalog(BaseModel)
```

Every declared member action across the registered accounts providers.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `actions` | `list[MemberActionDescriptor]` |

## MemberActionDescriptor

`tai42_contract.accounts.models.MemberActionDescriptor`

```python theme={null}
class MemberActionDescriptor(BaseModel)
```

One declared member action, serialized for the catalog wire.

`key` is the opaque catalog key the platform mints for (provider, action) — a caller
joins and echoes it, never parses it. `label` is the resolved wording (the
declaration's `TemplatedText` rendered at the door). `input_schema` and
`result_schema` are the declared models' `model_json_schema()` — a caller renders
a form and a read-only result view from them generically, with no provider field name
known to the platform.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `key` | `str` |
| `label` | `str` |
| `scope` | `MemberActionScope` |
| `destructive` | `bool` |
| `input_schema` | `dict[str, Any]` |
| `result_schema` | `dict[str, Any]` |

## MemberActionScope

`tai42_contract.accounts.models.MemberActionScope`

```python theme={null}
MemberActionScope = Literal['page', 'member_row', 'invite_row']
```

Where a declared member action renders: a page-level button, a member-row menu item,
or an invite-row menu item. A provider classifies each of its own actions into one of
these three places; the platform never reads the provider's meaning behind it.

## MemberDirectory

`tai42_contract.accounts.models.MemberDirectory`

```python theme={null}
class MemberDirectory(BaseModel)
```

The aggregated, platform-joined membership the Members door returns.

The wire shape of the deployment-wide Members view: every provider's people and
invitations as `MemberRow` / `InviteRow`, each carrying opaque routing
tokens and (for a member) the platform-joined principal state. The provider's raw
action ids and principal ids never reach this wire.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `members` | `list[MemberRow]` |
| `invites` | `list[InviteRow]` |

## MemberEntry

`tai42_contract.accounts.models.MemberEntry`

```python theme={null}
class MemberEntry(BaseModel)
```

One person an accounts provider owns: an account the operator manages.

`id` is the provider's stable handle for the person — the id its own actions act on.
`email` is the sign-in identity the provider holds for them. `created_at` is
timezone-aware (UTC).

`principal_ids` are the platform principal id(s) this person holds (at least one — a
person with none is an invitation, not a member); the Members operation joins them
against the platform's own records to resolve each principal's access-control
`disabled` state and the role it holds. Neither is a provider fact, so neither rides
here. `actions` are the provider's OWN member-action ids applicable to this row.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `id` | `str` |
| `email` | `str` |
| `created_at` | `datetime` |
| `principal_ids` | `list[str]` |
| `actions` | `list[str]` |

## MemberListing

`tai42_contract.accounts.models.MemberListing`

```python theme={null}
class MemberListing(BaseModel)
```

An accounts provider's membership: the people it owns and the invitations it holds.

Returned by `list_members`.
The application's Members aggregation concatenates one of these per registered
accounts provider into a single deployment-wide view, so a provider's people and
outstanding invitations appear without the platform naming the provider.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `members` | `list[MemberEntry]` |
| `invites` | `list[InviteEntry]` |

## MemberPrincipalState

`tai42_contract.accounts.models.MemberPrincipalState`

```python theme={null}
class MemberPrincipalState(BaseModel)
```

One platform principal a member holds, with its access-control state joined in.

`user_id` is the platform principal id; `disabled` is taken from that principal's
own record (the store the principals listing reads) and `role` is the role it holds,
joined from its own policy record — both never from a provider. `role` is `None`
when the principal's policy was not written from a role template.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `user_id` | `str` |
| `disabled` | `bool` |
| `role` | `_RoleName` |

## MemberRow

`tai42_contract.accounts.models.MemberRow`

```python theme={null}
class MemberRow(BaseModel)
```

A member row in the aggregated directory the Members door returns.

Display fields plus the platform-joined principal state and opaque routing tokens.
`handle` routes an invoke back to the producing provider and pins this row;
`action_keys` are the opaque catalog keys of the actions applicable to it — a caller
joins and echoes both, never parses them. `principals` carries each principal's
joined state; `disabled` is derived True only when EVERY principal is disabled, so a
person with any enabled principal still reads active while the per-principal truth
stays visible. `role` is derived too: the one name every principal holds, `None`
when there is no single name — every principal's policy was set directly, or the
principals hold different roles; `principals[].role` carries each principal's own.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `id` | `str` |
| `email` | `str` |
| `role` | `_RoleName` |
| `created_at` | `datetime` |
| `principals` | `list[MemberPrincipalState]` |
| `disabled` | `bool` |
| `handle` | `str` |
| `action_keys` | `list[str]` |

## PasswordCredential

`tai42_contract.accounts.models.PasswordCredential`

```python theme={null}
class PasswordCredential(BaseModel)
```

A login credential that sets the principal's password now.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `kind` | `Literal['password']` |
| `email` | `str` |
| `password` | `str` |


# Agents (tai42_contract.agent)
Source: https://docs.tai42.ai/reference/python-sdk/contract-agent

The Agent base class plugin authors subclass.

Agent contract: the `Agent` ABC + its neutral streamed-event vocabulary.

Re-exports the `Agent` interface (its `PresetSpec` input, `AddressedMemory` answer, the
`TOOL_NAME_MAX_LEN` / `PRESET_NAME_PATTERN` laws and `AgentInterruptedError` error)
alongside the `StreamEvent` types an agent's `astream` yields and `run` drains.

## PRESET\_NAME\_PATTERN

`tai42_contract.agent.base.PRESET_NAME_PATTERN`

```python theme={null}
PRESET_NAME_PATTERN: Final[str] = f'^[A-Za-z0-9_-]{{1,{TOOL_NAME_MAX_LEN}}}$'
```

## TOOL\_NAME\_MAX\_LEN

`tai42_contract.agent.base.TOOL_NAME_MAX_LEN`

```python theme={null}
TOOL_NAME_MAX_LEN: Final[int] = 64
```

## AddressedMemory

`tai42_contract.agent.base.AddressedMemory`

```python theme={null}
class AddressedMemory(BaseModel)
```

The memory a set of run kwargs addresses, as the agent reads them.

`keys` names the run kwargs present that steer THIS run's own thread or checkpoint
continuity (resuming, the checkpoint the run continues from, the checkpointer it runs on) — the
keys a door that owns the run's identity refuses. A key that only configures a sub-role's memory
is not one of them; its thread and checkpoint ids are still reported in `thread_ids` /
`checkpoint_ids`.

**Attributes**

| Attribute | Type |
| - | - |
| `keys` | `frozenset[str]` |
| `thread_ids` | `frozenset[str]` |
| `checkpoint_ids` | `frozenset[str]` |

## Agent

`tai42_contract.agent.base.Agent`

```python theme={null}
class Agent(ABC)
```

The uniform agent contract.

Implement `run`; override `astream` only when the agent produces real per-step
events.

Subclasses declare three class attributes that drive auto-tool generation:

* `tool_name` — the registered name (also the auto-generated tool name);
* `tool_description` — the LLM-facing description (carried, not lost);
* `ToolInput` — a JSON-able pydantic model of the tool params. Live
  `tools=` is deliberately NOT in `ToolInput` (API-only via `astream`);
  a non-JSON field fails loudly at `model_json_schema()` time.

`spec_runnable` is a capability marker (default `False`):
`spec_runnable = True` declares that this agent's `ToolInput` advertises
EXACTLY the composable fields its runtime honors — no more, no less. This lets
a generic UI gate authoring controls on the input schema's fields: it renders a
control only for an advertised (honored) field, and baking an un-advertised
field is rejected at author time. The declaration is the implementation's — it
is never inferred, and no agent name is ever hardcoded. Because every
`ToolInput` field of a `spec_runnable` agent is honored, all of them are
preset-bakeable; `preset_bakeable_fields` covers the other case.

`preset_bakeable_fields` names the `ToolInput` fields whose baked
(preset `fixed_kwargs`) value the runtime honors on an agent that is NOT
UI-composable — declaring a field here implies no UI control at all, only that
a hidden baked value is passed through and acted on. A field is preset-bakeable
iff the agent is `spec_runnable` (all fields, above) OR the field is listed
here. Like `spec_runnable` it is the implementation's own declaration, never
inferred; every listed name must be a real `ToolInput` field. The empty
default means nothing is bakeable unless the agent is `spec_runnable`.

`tool_names` is the FIXED tool set this agent always binds — the
statically-declared set a bind check reads to judge what the agent will run
with (e.g. whether it can ask its caller). `None` (the default) declares an
agent that resolves its tool set per call (from its `ToolInput`/run kwargs),
so nothing static is known. An agent whose tool set is fixed declares it here;
like `spec_runnable` it is the implementation's own declaration, never
inferred.

`parks` declares that this agent can suspend on an async ask raised by a
tool it runs and resume out of band (it emits `SuspendedFinal`). Like
`spec_runnable` it is the implementation's own declaration, never inferred; a
consumer reads it to know whether a run of this agent can park.

**Attributes**

| Attribute | Type |
| - | - |
| `tool_name` | `str` |
| `tool_description` | `str` |
| `ToolInput` | `type[BaseModel]` |
| `spec_runnable` | `bool` |
| `preset_bakeable_fields` | `frozenset[str]` |
| `tool_names` | `Sequence[str] \| None` |
| `extras_keys` | `frozenset[str]` |
| `parks` | `bool` |

### Members

#### addressed\_memory

`tai42_contract.agent.base.Agent.addressed_memory`

```python theme={null}
addressed_memory(cls, run_kwargs: Mapping[str, Any]) -> AddressedMemory
```

Report the memory `run_kwargs` (the output of `from_tool_input`) address.

The names of the run kwargs present that steer the run's memory or continuity (`keys`),
and every thread id and checkpoint id they carry, however nested. The platform reserves
thread namespaces and decides caller pinning from this answer, so an agent that carries a
thread or checkpoint anywhere in its run kwargs MUST report it. An agent with no memory
returns `AddressedMemory()`. The contract's own `thread_id` keyword is checked by the
platform itself and need not be reported.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `run_kwargs` | `Mapping[str, Any]` | — | — |

#### from\_tool\_input

`tai42_contract.agent.base.Agent.from_tool_input`

```python theme={null}
from_tool_input(cls, validated: BaseModel) -> dict[str, Any]
```

Map a validated `ToolInput` instance to `run` kwargs.

Passes through every set field with nested pydantic values (`presets`,
`subagents`, `inline_skills`) kept as model instances, since `run`
and the resolvers it calls read them by attribute. `model_dump` is
deliberately NOT used — it would flatten those nested models to dicts.
Agents whose JSON tool-face shape differs from their `run` signature
override this.

Any error an override raises must be a constant, hand-authored message and
must NOT interpolate input values: the agent run routes surface these
messages verbatim to the caller, and the baked input can carry credentials
the caller is not entitled to see.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `validated` | `BaseModel` | — | — |

#### run

`tai42_contract.agent.base.Agent.run`

```python theme={null}
async run(
    self,
    *,
    thread_id: str | None = None,
    user_message: TemplatedText | None = None,
    tool_names: Sequence[str] = (),
    response_format: TemplatedText | dict[str, Any] | None = None,
    **kwargs: Any,
) -> Any
```

Run the agent once and return its final value.

`thread_id`, `user_message`, `tool_names` and `response_format` are the keys the
platform supplies or reads; every other keyword is the agent's own, declared by its
`ToolInput` and documented by the agent. `response_format`: a JSON-Schema `dict` MUST
carry a non-empty top-level `title` (the structured-output name the run forces), and each
`oneOf` variant its own; a `TemplatedText` names a stored schema rendered at the point of
use; an in-process pydantic class (an agent's own widening of this parameter) carries its
class name.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str \| None` | `None` | — |
| `user_message` | `TemplatedText \| None` | `None` | — |
| `tool_names` | `Sequence[str]` | `()` | — |
| `response_format` | `TemplatedText \| dict[str, Any] \| None` | `None` | — |
| `kwargs` | `Any` | `{}` | — |

#### astream

`tai42_contract.agent.base.Agent.astream`

```python theme={null}
async astream(self, **kwargs: Any) -> AsyncIterator[StreamEvent]
```

Free default for non-streaming agents: run once, emit one terminal.

The terminal type matches the result: a `str` becomes a
`MessageFinal` (plain-text answer), any other value a
`StructuredFinal` (the structured `response_format` object).
Streaming agents override this with the real per-step projection and
implement `run` by draining their own `astream` via
`_drain`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kwargs` | `Any` | `{}` | — |

#### append\_thread\_messages

`tai42_contract.agent.base.Agent.append_thread_messages`

```python theme={null}
async append_thread_messages(self, *, thread_id: str, messages: list[dict[str, str]], **kwargs: Any) -> None
```

Append `messages` to `thread_id`'s stored history WITHOUT running the agent.

Each item is `{"role": "user"|"assistant", "content": str}`. The conversation
bridge calls this to record a manual-mode inbound and an operator's outbound reply
into the thread's memory, so a later agent turn reads them as prior context. An
agent with no thread memory raises `NotImplementedError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |
| `messages` | `list[dict[str, str]]` | — | — |
| `kwargs` | `Any` | `{}` | — |

## AgentInterruptedError

`tai42_contract.agent.base.AgentInterruptedError`

```python theme={null}
class AgentInterruptedError(Exception)
```

Raised by `run`/`_drain` when a non-streaming caller drains a run that paused on an interrupt.

A non-streaming caller cannot act on an interrupt, so it surfaces loudly rather than
returning a partial. `interrupts` is the list of `InterruptFinal` events the run
emitted.

**Attributes**

| Attribute | Type |
| - | - |
| `interrupts` | — |

## AsksFinal

`tai42_contract.agent.events.AsksFinal`

```python theme={null}
class AsksFinal(StreamEvent)
```

The agent run asked its CALLER one or more questions before it could answer. Terminal.

A `to="caller"` ask is addressed to the run's own caller — here the SSE client driving the
stream — so the run cannot proceed until the caller answers it, unlike a `to="user"` park
(`SuspendedFinal`) whose answer arrives out of band. `asks` carries the full parked
entries the caller must answer (id, question, answer format, and the rest of the parked-entry
shape); the vocabulary is generic — it names no driver, engine, or resume state.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['asks_final']` |
| `asks` | `list[dict[str, Any]]` |
| `final` | `bool` |

## InterruptFinal

`tai42_contract.agent.events.InterruptFinal`

```python theme={null}
class InterruptFinal(StreamEvent)
```

A platform interrupt surfaced out of a paused agent graph. Terminal.

`interrupt_id` is the graph interrupt id (echoed back when resuming);
`payload` is the interrupt value the agent raised (e.g. the option set);
`reason` is an optional human-facing label. This event is emitted verbatim
as one SSE frame (`type: "interrupt_final"`); a consumer reads
`interrupt_id`, `payload` and `reason` off it — do NOT rename `payload`
or drop `reason`.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['interrupt_final']` |
| `interrupt_id` | `str` |
| `payload` | `Any` |
| `reason` | `str \| None` |
| `final` | `bool` |

## MessageDelta

`tai42_contract.agent.events.MessageDelta`

```python theme={null}
class MessageDelta(StreamEvent)
```

A token-level chunk of the agent's final answer as it streams.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['message_delta']` |
| `text` | `str` |

## MessageFinal

`tai42_contract.agent.events.MessageFinal`

```python theme={null}
class MessageFinal(StreamEvent)
```

The agent's complete final answer, assembled from the deltas. Terminal.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['message_final']` |
| `text` | `str` |
| `final` | `bool` |

## PresetSpec

`tai42_contract.agent.base.PresetSpec`

```python theme={null}
class PresetSpec(BaseModel)
```

A base tool bound to fixed kwargs, bound as one more tool of the run that carries it.

`name` follows `PRESET_NAME_PATTERN`. A base tool that interprets its fixed kwargs as a
nested document carries that document opaquely here.

**Attributes**

| Attribute | Type |
| - | - |
| `name` | `str` |
| `description` | `str` |
| `base_tool` | `str` |
| `fixed_kwargs` | `dict[str, Any]` |

## ReasoningStep

`tai42_contract.agent.events.ReasoningStep`

```python theme={null}
class ReasoningStep(StreamEvent)
```

A chunk of the model's intermediate reasoning ("thinking") for one step of the agent loop.

Empty/whitespace-only reasoning is never emitted.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['reasoning_step']` |
| `text` | `str` |

## RecursionLimitFinal

`tai42_contract.agent.events.RecursionLimitFinal`

```python theme={null}
class RecursionLimitFinal(StreamEvent)
```

The run hit the graph's step (`recursion_limit`) ceiling before it finished. Terminal, non-fatal.

A runaway loop that exhausts the super-step budget ends with this typed,
readable outcome instead of a generic failure, so a flow or route can branch
on it. `limit` is the super-step ceiling that was hit; `steps` is what is
known of the step count when the graph reports it, else `None`.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['recursion_limit_final']` |
| `limit` | `int` |
| `steps` | `int \| None` |
| `final` | `bool` |

## RunUsage

`tai42_contract.agent.events.RunUsage`

```python theme={null}
class RunUsage(StreamEvent)
```

Token usage (and model label) for the run. Any field may be `None`.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['run_usage']` |
| `input_tokens` | `int \| None` |
| `output_tokens` | `int \| None` |
| `total_tokens` | `int \| None` |
| `model` | `str \| None` |

## StreamEvent

`tai42_contract.agent.events.StreamEvent`

```python theme={null}
class StreamEvent(BaseModel)
```

Base class for every event an `Agent` streams.

`type` is a stable discriminator; `final` marks a terminal event (see the terminal
rule in `Agent._drain`).

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `type` | `str` |
| `final` | `bool` |

## StructuredFinal

`tai42_contract.agent.events.StructuredFinal`

```python theme={null}
class StructuredFinal(StreamEvent)
```

The agent's structured (non-text) output.

`data` is the object the agent produced — typically the validated `response_format`
instance. A plain-text answer is carried by `MessageFinal` instead. Terminal.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['structured_final']` |
| `data` | `Any` |
| `final` | `bool` |

## StructuredOutputUnresolvedFinal

`tai42_contract.agent.events.StructuredOutputUnresolvedFinal`

```python theme={null}
class StructuredOutputUnresolvedFinal(StreamEvent)
```

The model never produced output conforming to the requested `response_format`. Terminal, non-fatal.

The structured-output rail re-prompted the model each time its final answer
failed to parse or validate against the schema, or carried no structured answer,
and the per-run re-prompt cap was reached with no conforming response. The run
ends with this typed outcome — branchable like a tool error — rather than looping
to the recursion limit or surfacing a generic failure. `schema_name` names the
requested schema; `attempts` is how many non-conforming responses the model
produced (the re-prompt cap plus the final rejected attempt); `error` is the
last error text — a validation error, or the message naming the missing
structured answer — masked as every recorded error is.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['structured_output_unresolved_final']` |
| `schema_name` | `str` |
| `attempts` | `int` |
| `error` | `str` |
| `final` | `bool` |

## SuspendedFinal

`tai42_contract.agent.events.SuspendedFinal`

```python theme={null}
class SuspendedFinal(StreamEvent)
```

A generic async park surfaced out of a paused agent graph. Terminal.

The run parked on one or more async `ask` questions and will resume out
of band when their answers (or expiries) arrive — it did NOT fail and did NOT
stop for a live decision, so a non-streaming drain returns a suspended RECEIPT
for it rather than raising `AgentInterruptedError`.

`interaction_ids` are the parked questions the resume converges on;
`caller_interaction_ids` is the subset of them addressed to the CALLER
(`to="caller"`), empty for a park of only user asks — the two id lists let the
platform's `visit` normalise a caller-ask park inside an agent into its
caller/user partition; `expiry_at` is the step's deadline — the latest of its parks'
deadlines (ISO-8601, or `None` when no park carried one); `thread_id` is the parked run's thread. The
vocabulary is generic — it names no driver, engine, or resume state, only the parked
interaction ids the flow-blind platform already holds.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['suspended_final']` |
| `interaction_ids` | `list[str]` |
| `thread_id` | `str` |
| `caller_interaction_ids` | `list[str]` |
| `expiry_at` | `str \| None` |
| `final` | `bool` |

### Members

#### to\_suspended\_interaction

`tai42_contract.agent.events.SuspendedFinal.to_suspended_interaction`

```python theme={null}
to_suspended_interaction(self) -> SuspendedInteraction
```

The park as the shared typed sentinel the platform's `visit` recognises by type.

It carries the whole super-step's two id lists, so `visit` normalises it per ask, and the
step's deadline. It carries NO `resume_owner`: the parked run recorded its own resume
state against those interactions and is the only thing the platform resumes for them, so no
caller may adopt the park as its own.

## ToolCallStep

`tai42_contract.agent.events.ToolCallStep`

```python theme={null}
class ToolCallStep(StreamEvent)
```

One tool invocation the agent decided to make.

`call_id` is the model-assigned id the matching `ToolResultStep` carries.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['tool_call_step']` |
| `tool` | `str` |
| `args` | `dict[str, Any]` |
| `call_id` | `str` |

## ToolResultStep

`tai42_contract.agent.events.ToolResultStep`

```python theme={null}
class ToolResultStep(StreamEvent)
```

The value one tool call returned, matched to a `ToolCallStep` by `call_id`.

`result` is passed through untouched.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['tool_result_step']` |
| `tool` | `str` |
| `call_id` | `str` |
| `result` | `Any` |
| `is_error` | `bool` |

## agent\_session\_thread

`tai42_contract.agent.session_thread.agent_session_thread`

```python theme={null}
agent_session_thread(thread_id: str) -> Generator[None]
```

Deposit `thread_id` as the ambient session thread for the wrapped block.

The deposit is reset in a `finally`. A task created inside the block inherits it on a
copy. Absent this wrap the deposit stays `None` and a run mints its own fresh thread.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |

## final\_event\_for\_value

`tai42_contract.agent.events.final_event_for_value`

```python theme={null}
final_event_for_value(value: Any) -> MessageFinal | StructuredFinal
```

The terminal event a plain agent result value represents.

A `str` is a plain-text answer (`MessageFinal`); any other value is structured output
(`StructuredFinal`, its `data`). The single rule both the non-streaming `astream`
default and a resumed run's plain terminal map a raw value through, so every path surfaces the
same final shape.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `Any` | — | — |

## get\_agent\_session\_thread

`tai42_contract.agent.session_thread.get_agent_session_thread`

```python theme={null}
get_agent_session_thread() -> str | None
```

The session thread deposited for the current run, or `None` when none is set.

## reset\_agent\_session\_thread

`tai42_contract.agent.session_thread.reset_agent_session_thread`

```python theme={null}
reset_agent_session_thread(token: Token[str | None]) -> None
```

Restore the session thread to the value captured in `token`.

`token` is the return value of the matching `set_agent_session_thread` call.

**Parameters**

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

## set\_agent\_session\_thread

`tai42_contract.agent.session_thread.set_agent_session_thread`

```python theme={null}
set_agent_session_thread(thread_id: str | None) -> Token[str | None]
```

Bind `thread_id` as the current run's session thread.

Pass the returned token to `reset_agent_session_thread` to restore the previous value.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str \| None` | — | — |


# App facade (tai42_contract.app)
Source: https://docs.tai42.ai/reference/python-sdk/contract-app

The assembled TaiApp facade and its per-feature namespaces.

The assembled `TaiApp` facade.

One `Protocol` per feature (see `tai42_contract.app.facets`), composed into
a single `TaiApp` protocol that exposes them as namespaces (`app.tools`,
`app.agents`, ...). The app members are partitioned across the
sub-protocols — each lives in exactly one, save the shared leaf names
`store` (`versioning` + `presets` + `tool_meta`) and `register`/`get`
(`webhook_verifiers` + `channels`). The runtime forwarding handle is
`tai42_app` (see `tai42_contract.app.handle`).

## DEFAULT\_LOCAL\_PORT

`tai42_contract.app.DEFAULT_LOCAL_PORT`

```python theme={null}
DEFAULT_LOCAL_PORT: Final = 8000
```

## AppAccounts

`tai42_contract.app.facets.integrations.AppAccounts`

```python theme={null}
class AppAccounts(Protocol)
```

Read access to the CURRENT epoch's live identity/accounts provider instances.

An accounts-provider plugin ships login routes that need the SAME provider instance
the epoch built and probed (its resolved config, cached discovery/JWKS, injected
settings). Rather than a module-level holder — which a failed epoch build would
leave pointing at a half-built generation — the plugin's routes resolve the live
instance here. The contract exposes only this read; the runtime forwards it to the
current epoch, so the contract never learns about epochs.

### Members

#### active\_provider

`tai42_contract.app.facets.integrations.AppAccounts.active_provider`

```python theme={null}
active_provider(self, name: str) -> IdentityProvider | None
```

The provider the CURRENT epoch instantiated under `name`, or `None` when none is active.

An `AccountsProvider` is an `IdentityProvider`. `None` means no provider is
active under that name — the name is not configured, or a build is mid-flight.

**Parameters**

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

#### authenticated\_credential

`tai42_contract.app.facets.integrations.AppAccounts.authenticated_credential`

```python theme={null}
authenticated_credential(self, request: Request) -> str | None
```

The raw credential the access-control gate authenticated `request` with.

When a request presents several credentials, this is the one that verified, not
merely the first presented. `None` when the request is unauthenticated or access
control is off.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `request` | `Request` | — | — |

## AppAdmin

`tai42_contract.app.facets.runtime.AppAdmin`

```python theme={null}
class AppAdmin(Protocol)
```

In-process admin operations: MCP binding, tool reload, config reload.

### Members

#### reload\_mcp

`tai42_contract.app.facets.runtime.AppAdmin.reload_mcp`

```python theme={null}
reload_mcp(self, title: str) -> dict[str, Any]
```

Rebind the MCP server titled `title` and return its status.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `title` | `str` | — | — |

#### deregister\_mcp

`tai42_contract.app.facets.runtime.AppAdmin.deregister_mcp`

```python theme={null}
deregister_mcp(self, title: str) -> dict[str, Any]
```

Remove the MCP server titled `title` and return its status.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `title` | `str` | — | — |

#### reload\_config

`tai42_contract.app.facets.runtime.AppAdmin.reload_config`

```python theme={null}
reload_config(self) -> dict[str, Any]
```

Re-init the process config in place and return the reload report.

#### tool\_reloader

`tai42_contract.app.facets.runtime.AppAdmin.tool_reloader`

```python theme={null}
tool_reloader(self, kind: str) -> Callable[..., Any]
```

Register an async `(action, name) -> dict` reloader for `kind`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `str` | — | — |

#### run\_tool\_reload

`tai42_contract.app.facets.runtime.AppAdmin.run_tool_reload`

```python theme={null}
async run_tool_reload(self, kind: str, action: str, name: str) -> dict[str, Any]
```

Run the registered `kind` reloader for `action` on `name`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `str` | — | — |
| `action` | `str` | — | — |
| `name` | `str` | — | — |

#### reload\_failed\_mcps

`tai42_contract.app.facets.runtime.AppAdmin.reload_failed_mcps`

```python theme={null}
reload_failed_mcps(self) -> list[dict[str, Any]]
```

Retry every MCP that failed to bind and return their statuses.

#### reprobe\_failed\_mcps

`tai42_contract.app.facets.runtime.AppAdmin.reprobe_failed_mcps`

```python theme={null}
async reprobe_failed_mcps(self, titles: list[str]) -> list[dict[str, Any]]
```

Re-probe those of `titles` that failed to bind, bind the recovered ones, and return their statuses.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `titles` | `list[str]` | — | — |

#### list\_failed\_mcps

`tai42_contract.app.facets.runtime.AppAdmin.list_failed_mcps`

```python theme={null}
list_failed_mcps(self) -> list[dict[str, Any]]
```

List the MCPs that failed to bind.

#### live\_mcp\_status

`tai42_contract.app.facets.runtime.AppAdmin.live_mcp_status`

```python theme={null}
live_mcp_status(self) -> dict[str, Any]
```

Snapshot the in-process MCP-binding state.

#### live\_manifest

`tai42_contract.app.facets.runtime.AppAdmin.live_manifest`

```python theme={null}
live_manifest: dict[str, Any]
```

The manifest currently live in this process.

## AppAgents

`tai42_contract.app.facets.execution.AppAgents`

```python theme={null}
class AppAgents(Protocol)
```

The agent-provider namespace (`app.agents`).

### Members

#### agent

`tai42_contract.app.facets.execution.AppAgents.agent`

```python theme={null}
agent(
    self,
    name: str,
    tags: set[str] | None = None,
    meta: dict[str, Any] | None = None,
) -> Callable[[type[_AgentT]], type[_AgentT]]
```

Register an `Agent` subclass under `name` and auto-register its JSON `run` tool.

`tags` are the run tool's native tags, set on its constructed tool object.
`meta` is generic registration metadata threaded onto the same constructed
run-tool object (naming no consumer concept — a registrant attaches any key of
`tai42_contract.tools.meta`, e.g. `TOOL_META_CRASH_RESUME`, which the
run-dispatch seam reads). The
decorator returns the class unchanged, so the decorated symbol keeps its
concrete subclass type.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `tags` | `set[str] \| None` | `None` | — |
| `meta` | `dict[str, Any] \| None` | `None` | — |

#### get\_agent

`tai42_contract.app.facets.execution.AppAgents.get_agent`

```python theme={null}
get_agent(self, name: str) -> Agent
```

Fetch a registered agent instance by name; raise if missing.

**Parameters**

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

#### all\_agents

`tai42_contract.app.facets.execution.AppAgents.all_agents`

```python theme={null}
all_agents(self) -> dict[str, Agent]
```

Return every registered agent keyed by registration name.

The result is a shallow copy, so a caller iterating it cannot mutate the live registry. The preset
bind kernel reads the keys to detect an agent base (the run tool binds under the registration name).

## AppBackends

`tai42_contract.app.facets.execution.AppBackends`

```python theme={null}
class AppBackends(Protocol)
```

The backend-provider namespace (`app.backends`).

### Members

#### register\_backend

`tai42_contract.app.facets.execution.AppBackends.register_backend`

```python theme={null}
register_backend(self, cls: type[Backend] | None = None) -> Callable[[type[Backend]], type[Backend]] | type[Backend]
```

Register the `Backend` provider; usable bare or as a decorator factory.

#### backend

`tai42_contract.app.facets.execution.AppBackends.backend`

```python theme={null}
backend: Backend | None
```

The registered backend provider, or `None` when none is registered.

## AppBackup

`tai42_contract.app.facets.runtime.AppBackup`

```python theme={null}
class AppBackup(Protocol)
```

Registry for named backup sections and the run of one section's export/import.

A plugin (or the host itself, the first consumer) registers a section under
`name` by supplying an `exporter()` that returns a JSON-safe payload and
an `importer(payload)` that applies it and returns a `BackupSectionReport`.
`sections()` lists the registered sections for the UI. `export_section`
/ `import_section` run one section's exporter/importer by name and raise
loudly on an unknown name — never a silent no-op. `import_section` also
validates the importer's result against `BackupSectionReport` and raises
naming the section on a wrong shape, so the platform never reads keys out of an
opaque object.

### Members

#### register\_section

`tai42_contract.app.facets.runtime.AppBackup.register_section`

```python theme={null}
register_section(
    self,
    name: str,
    exporter: Callable[[], Any],
    importer: Callable[[Any], Any],
    *,
    secret: bool = False,
) -> None
```

Register a backup section's exporter/importer under `name`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `exporter` | `Callable[[], Any]` | — | — |
| `importer` | `Callable[[Any], Any]` | — | — |
| `secret` | `bool` | `False` | — |

#### sections

`tai42_contract.app.facets.runtime.AppBackup.sections`

```python theme={null}
sections(self) -> list[BackupSectionInfo]
```

List the registered backup sections.

#### export\_section

`tai42_contract.app.facets.runtime.AppBackup.export_section`

```python theme={null}
export_section(self, name: str) -> Any
```

Run one section's exporter by `name` and return its payload.

**Parameters**

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

#### import\_section

`tai42_contract.app.facets.runtime.AppBackup.import_section`

```python theme={null}
async import_section(self, name: str, payload: Any) -> BackupSectionReport
```

Apply `payload` via one section's importer by `name`, returning the validated report.

Awaits an async importer, validates its result against
`BackupSectionReport`, and raises naming the section on a wrong shape.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `payload` | `Any` | — | — |

## AppChannels

`tai42_contract.app.facets.messaging.AppChannels`

```python theme={null}
class AppChannels(Protocol)
```

The channel registry namespace (`app.channels`) and inbound-answer ladder.

### Members

#### register

`tai42_contract.app.facets.messaging.AppChannels.register`

```python theme={null}
register(self, name: str, channel: Channel) -> None
```

Register a `Channel` under `name`.

A channel plugin calls this through the `tai42_app` handle when its
import-only `channel_modules` entry loads. Registering a name already
taken raises loudly — a silent overwrite could swap the medium a live
ask is delivered on.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `channel` | `Channel` | — | — |

#### get

`tai42_contract.app.facets.messaging.AppChannels.get`

```python theme={null}
get(self, name: str) -> Channel
```

Fetch a registered channel by name; raise loudly on an unknown name.

Resolution happens when `ask` is called with `channel=name`,
BEFORE any interaction state is written, so an unknown name surfaces as
a loud failure, never a question silently delivered nowhere.

**Parameters**

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

#### names

`tai42_contract.app.facets.messaging.AppChannels.names`

```python theme={null}
names(self) -> list[str]
```

Every registered channel name, for the channels catalog route.

#### handle\_inbound\_answer

`tai42_contract.app.facets.messaging.AppChannels.handle_inbound_answer`

```python theme={null}
async handle_inbound_answer(
    self,
    *,
    channel_id: str,
    correlation_key: str,
    answer: Any,
    store: CorrelationStore,
    bridge: InboundBridge,
) -> InboundAnswerResult
```

Resolve one inbound participant reply against its pending ask.

This is the ONE shared inbound-answer ladder every correlated channel calls
instead of hand-rolling its own "forward → interpret 2xx/404/400 →
release/bridge/keep" sequence.

Returns an `InboundAnswerResult`: the `outcome` the channel maps to its
transport ack, plus the door's `retry_reason`/`retry_field` when it rejected
the answer's content, so a channel that owns its correction surface can render the
door's specific message.

A channel computes its own opaque `correlation_key` for the participant's address,
provides the `answer` value to forward to the door, its
`CorrelationStore`, and an `InboundBridge` of the
fields a bridged turn needs.

SEAM SYMMETRY (`bridge.params` ↔ answer params): the `InboundBridge` may carry opaque
channel enrichment in `params` — the answer-path counterpart of a conversation entry's
`params`. The ladder threads it BOTH ways so enrichment is never dropped on either arm:
the answer is forwarded to the ask's callback door as `{"answer": answer, "params":
params}` (params present only when set), landing on
`params` for the asking flow
to read beside `answer`; and on the BRIDGE arm the same `params` are passed to
`accept` as its entry `params`. `bridge.medium_message_id` rides both arms the same
way: in the callback body as `medium_message_id` (landing on
`medium_message_id`) and to
`accept` on the bridge arm. `bridge.reply_to_medium_message_id`, the id of the message
the reply quotes, rides both arms likewise: in the callback body as
`reply_to_medium_message_id` (present only when set, landing on
`reply_to_medium_message_id`)
and to `accept` on the bridge arm. The ladder:

* No pending ask on the key -> `InboundAnswerOutcome.NO_CORRELATION`
  with NO side effect: the CALLER bridges the reply as a normal turn (the
  ladder never bridges on a miss, exactly as each channel did by hand).
* The door accepts (2xx) -> release the correlation, return
  `InboundAnswerOutcome.FORWARDED`.
* The door returns 404 (the ask was withdrawn/expired/cancelled) -> release,
  bridge the reply as a fresh turn, return `InboundAnswerOutcome.BRIDGED`.
* The door returns 400 on a LIVE ask -> read the door's `retry_in_place`
  (default True): True keeps the correlation, notifies the participant what's
  expected, fires ONE operator event, returns `InboundAnswerOutcome.RETRY_KEPT`;
  False (a hard mismatch) releases, notifies the participant the question is closed,
  fires the event, bridges the reply, returns `InboundAnswerOutcome.BRIDGED`.
* Anything else (401/413/5xx, or a transport fault) -> do NOT release; raise
  `AnswerForwardError` so the channel's webhook redelivery re-runs the
  ladder. The answer is never silently lost.

The callback host is pinned to the platform's configured public base before the
forward; a stored callback whose host does not match is released and treated as
`InboundAnswerOutcome.NO_CORRELATION`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `channel_id` | `str` | — | — |
| `correlation_key` | `str` | — | — |
| `answer` | `Any` | — | — |
| `store` | `CorrelationStore` | — | — |
| `bridge` | `InboundBridge` | — | — |

#### record\_send\_receipt

`tai42_contract.app.facets.messaging.AppChannels.record_send_receipt`

```python theme={null}
async record_send_receipt(
    self,
    channel: str,
    provider_message_id: str,
    status: DeliveryReceipt,
    *,
    errors: Any = None,
) -> bool
```

Post an out-of-band delivery receipt for a `notify_user` send back onto its originating trace.

The send is a `notify_user` channel send with no conversation record. The tier-2
counterpart to the conversation bridge's `record_delivery_status`: a
channel's delivery-status webhook calls this when the bridge does not own the
outbound id (`record_delivery_status` raised `LookupError`). It resolves the id
through the TTL'd send-receipt index and, on a hit, emits a `delivery_receipt` event
into the recorded trace (a FAILED receipt at ERROR level), so the originating trace
shows delivered-vs-accepted for its sends. `errors` carries any provider error
detail for the event input.

Returns `True` when the id was a known send (event emitted), `False` when it
is not — so the webhook keeps its genuinely-unknown-id log only on a `False`. A
no-op returning `False` where the send-receipt store is unconfigured.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `channel` | `str` | — | — |
| `provider_message_id` | `str` | — | — |
| `status` | `DeliveryReceipt` | — | — |
| `errors` | `Any` | `None` | — |

## AppClients

`tai42_contract.app.facets.runtime.AppClients`

```python theme={null}
class AppClients(Protocol)
```

Pooled async client lifecycle for the process.

### Members

#### client\_ctx

`tai42_contract.app.facets.runtime.AppClients.client_ctx`

```python theme={null}
client_ctx(
    self,
    client_cls: type[BaseClient[ClientT]],
    settings: Any = None,
    *,
    fresh: bool = False,
    **kwargs: Any,
) -> AbstractAsyncContextManager[ClientT]
```

Yield a connected client as an async context manager.

Pooled per loop + connection params, or one-shot when `fresh=True`.
`settings` is a kit `ClientSettings` whose `client_kwargs()` supplies
the connection key.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `client_cls` | `type[BaseClient[ClientT]]` | — | — |
| `settings` | `Any` | `None` | — |
| `fresh` | `bool` | `False` | — |
| `kwargs` | `Any` | `{}` | — |

#### shutdown\_clients

`tai42_contract.app.facets.runtime.AppClients.shutdown_clients`

```python theme={null}
async shutdown_clients(self) -> None
```

Close every live client pool for the running loop.

## AppConfig

`tai42_contract.app.facets.runtime.AppConfig`

```python theme={null}
class AppConfig(Protocol)
```

Access to the process config manager.

### Members

#### config\_manager

`tai42_contract.app.facets.runtime.AppConfig.config_manager`

```python theme={null}
config_manager: ConfigManager
```

The process config manager.

## AppConnectors

`tai42_contract.app.facets.integrations.AppConnectors`

```python theme={null}
class AppConnectors(Protocol)
```

Registration and credential resolution for connector providers.

### Members

#### register\_connector

`tai42_contract.app.facets.integrations.AppConnectors.register_connector`

```python theme={null}
register_connector(self, descriptor: ProviderDescriptor) -> None
```

Register a connector provider from its pure descriptor data.

Called for every manifest `connectors` entry at boot/reload, and by any
code holding the handle (a connector is pure data, so this is a plain call,
not a decorator).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `descriptor` | `ProviderDescriptor` | — | — |

#### token\_store

`tai42_contract.app.facets.integrations.AppConnectors.token_store`

```python theme={null}
token_store: ConnectorTokenStore
```

The connector token store (single-namespace, keyed by `connection_id`).

#### resolve\_connection\_auth

`tai42_contract.app.facets.integrations.AppConnectors.resolve_connection_auth`

```python theme={null}
async resolve_connection_auth(self, connection_id: str, provider_id: str, sub_service: str) -> ResolvedConnectionAuth | None
```

Resolve the credential a connection injects, for the CURRENT caller.

The facade accessor an in-process plugin uses to read a skeleton-resolved
credential (OAuth token / static env / static headers) without importing the
skeleton — refreshing an expired OAuth token under the connection lock. Async
because resolution performs I/O (the OAuth refresh under the connection lock);
callers `await` it. Returns `None` when the connection injects nothing.

GUARANTEE (enforced by the skeleton implementation): (1) it RAISES a loud
constant-message error when NO execution identity is bound — the fail-close
raise fires as the awaited coroutine runs, BEFORE resolving, so an
identity-less door never gets creds injected; and
(2) `connection_id` is a REFERENCE supplied by operator settings, NEVER
session-supplied, so a session can neither reach an identity-less door's
creds nor name another connection. The contract carries no logic — the
skeleton owns the fail-close enforcement.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `connection_id` | `str` | — | — |
| `provider_id` | `str` | — | — |
| `sub_service` | `str` | — | — |

## AppConversations

`tai42_contract.app.facets.messaging.AppConversations`

```python theme={null}
class AppConversations(Protocol)
```

The conversation bridge's entry surface for medium adapters.

Inbound messages arrive via `accept`, out-of-band delivery receipts via
`record_delivery_status`. Routing-row CRUD, the turn engine and the API
door are not part of this facet.

### Members

#### accept

`tai42_contract.app.facets.messaging.AppConversations.accept`

```python theme={null}
async accept(
    self,
    channel: str,
    our_identity: str,
    client_address: str,
    cap_key: str,
    text: str,
    provider_message_id: str,
    medium_message_id: str | None,
    reply_to_medium_message_id: str | None,
    params: dict[str, str] | None = None,
    form: dict[str, Any] | None = None,
    attachments: list[MediaItem] | None = None,
    location: LocationElement | None = None,
    locale: str | None = None,
    form_tag: str | None = None,
) -> str
```

Accept one inbound channel message, persist it, and return its `message_id` (a uuid4).

Routed to the `door=channel` route matching `(channel, our_identity)`; the
turn runs as that route's execution key and answers back over the same channel.
Idempotent on `(channel, provider_message_id)` — a redelivery returns the
existing `message_id` and starts no second turn. Raises when no route matches.
`medium_message_id` is the id the medium gives the message itself, the one a later
quote names (`None` only when the medium has no such id); it is not the dedupe key.
One medium message bridged as several records passes the same `medium_message_id`
on each. `reply_to_medium_message_id` is the medium's id of the message this one
quotes (`None` when it quotes none); required, `None` included. A reply's quoted
message is a typed field: the platform resolves its text from the conversation record
and hands it to the target as `reply_to` (`ReplyTo`).

`client_address` is the conversation identity (its thread and transcript).
`cap_key` is the party the per-address turn cap holds accountable, which the
door composes: a provider channel passes its attested address (the two match),
a door that mints its own visitor id passes a key the platform does NOT mint —
its network client bucket — so the cap bounds spend the visitor cannot reset.
Required and non-blank; a door that omits it is refused, never defaulted.

`params` are optional entry parameters the door captured with the conversation
entry, delivered verbatim to a tool target's payload under `params`;
`None`/empty leaves the payload unchanged. The door validates them with
`validate_entry_params` before accept.
`params` is ALSO the opaque-enrichment seam for the channel-specific inbound
context that has no shared shape — a tapped reply/list id, a template button
payload, a referral, a contact card or a reaction — which a channel adapter encodes as
string entries a
route reads deliberately; the platform adds no typed field for those.

`form` is an optional structured participant submission (an ask-less form's answers)
riding WITH the required rendered `text` — the text stays the whole turn every
consumer sees, while a tool target's `start_expr` may map the structured copy
from the payload's `form` key (present only when the inbound carried one). The
platform bounds it as pure transport
(`validate_inbound_form`) and attaches no
meaning and NO TRUST to the contents: participant-shaped data, never schema-conformant.

`attachments` is the STRUCTURED media the participant sent WITH the message — the
inbound counterpart of an outbound answer's `media` — as `MediaItem`
(image/document/video/audio; a channel resolves a sticker to image/video, a voice
note to audio). `location` is a `LocationElement` the participant shared. Both
are machine-consumable content with a shared cross-channel shape, so they are typed
fields (not `params`): they land in a tool target's payload under the stable
`attachments` / `location` keys, present only when the inbound carried them, so
a form-/media-unaware target still sees the whole turn as `text`. `None` leaves
the payload unchanged.

`locale` is the participant's BCP 47 language tag the channel resolved from its native
inbound (a per-message language hint), captured onto the turn's subject so the
rendering layer resolves every text template and list format against it — flows and
state templates never select a language. It seeds a first-contact person's stored
locale and, absent a stored operator override, is the turn's resolved locale;
`None` means the channel supplied none (no silent default to any language).

`form_tag` is the caller-set opaque per-send correlation the platform handed out with
the form this submission answers, carried back by the channel and delivered to a tool
target's payload under the stable `form_tag` key BESIDE `form` (present only when the
inbound carried one). It REQUIRES `form` — a tag without a submission is refused — and
the platform bounds it as transport (`check_form_tag`)
but never interprets the value. `None` means the channel carried none.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `channel` | `str` | — | — |
| `our_identity` | `str` | — | — |
| `client_address` | `str` | — | — |
| `cap_key` | `str` | — | — |
| `text` | `str` | — | — |
| `provider_message_id` | `str` | — | — |
| `medium_message_id` | `str \| None` | — | — |
| `reply_to_medium_message_id` | `str \| None` | — | — |
| `params` | `dict[str, str] \| None` | `None` | — |
| `form` | `dict[str, Any] \| None` | `None` | — |
| `attachments` | `list[MediaItem] \| None` | `None` | — |
| `location` | `LocationElement \| None` | `None` | — |
| `locale` | `str \| None` | `None` | — |
| `form_tag` | `str \| None` | `None` | — |

#### record\_delivery\_status

`tai42_contract.app.facets.messaging.AppConversations.record_delivery_status`

```python theme={null}
async record_delivery_status(
    self,
    channel: str,
    provider_message_id: str,
    status: DeliveryReceipt,
    *,
    errors: Any = None,
) -> None
```

Ingest a channel's out-of-band delivery receipt for an outbound message.

`provider_message_id` is one of the ids a prior `notify` or `deliver` returned,
resolved to its record through the outbound-id reverse index. `FAILED` marks the
record failed; `DELIVERED` confirms a `provisional` record. `errors` is the
provider's error detail, carried onto the trace receipt event of a recorded
`notify_user` send. Raises when the id resolves to no record.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `channel` | `str` | — | — |
| `provider_message_id` | `str` | — | — |
| `status` | `DeliveryReceipt` | — | — |
| `errors` | `Any` | `None` | — |

#### send\_recorded

`tai42_contract.app.facets.messaging.AppConversations.send_recorded`

```python theme={null}
async send_recorded(
    self,
    *,
    channel: str,
    our_identity: str,
    client_address: str,
    content: AnswerPart,
    send: Callable[[], Awaitable[SendOutcome]],
) -> SendOutcome
```

Record a send a channel plugin makes itself, record first, and return its outcome.

The platform writes the send's record before `send` runs, runs it, then completes
the record from the returned `SendOutcome` (its identity, address and message
ids place the record). `our_identity` and `client_address` are the plugin's
pre-send address, used only to place a send that never reported an outcome.
`content` is what the send carries, recorded as the record's one part. A send
that raises leaves a failed record and its error propagates; a send with no
matching conversation route is sent unrecorded.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `channel` | `str` | — | — |
| `our_identity` | `str` | — | — |
| `client_address` | `str` | — | — |
| `content` | `AnswerPart` | — | — |
| `send` | `Callable[[], Awaitable[SendOutcome]]` | — | — |

#### notify\_inbound\_rejected

`tai42_contract.app.facets.messaging.AppConversations.notify_inbound_rejected`

```python theme={null}
async notify_inbound_rejected(
    self,
    *,
    channel_id: str,
    recipient: str,
    sender_identity: str,
    kind: str,
    reason: InboundRejectionReason,
) -> None
```

Reply once and record a platform event when an inbound content cannot become a turn.

The ONE shared chokepoint a channel adapter calls instead of silently ack-and-ignoring a
vendor content it recognises but cannot represent as a turn — an unmappable media kind, a
file over the platform cap, a byte source it could not fetch, or an unsupported content
type. Sends a single participant notice back over `channel_id` to `recipient` from
`sender_identity` (the receiving identity, the conversation route's key), and records a
platform event naming the generic `kind` refused and the `reason`, so the drop is
operator-visible. The notice is the route's `reply_texts` member for `reason`
(`rejected_<reason>`), else the built-in notice. `kind` is a generic, domain-neutral label
(e.g. an `InboundMediaKind` value or a channel's neutral
content word); it names WHAT was refused, never a participant value. `reason` selects the
notice the platform sends. A blank or unroutable message is a different fault and
stays its own handling — this seam is for content the channel recognises but cannot bridge.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `channel_id` | `str` | — | — |
| `recipient` | `str` | — | — |
| `sender_identity` | `str` | — | — |
| `kind` | `str` | — | — |
| `reason` | `InboundRejectionReason` | — | — |

#### pending\_messages

`tai42_contract.app.facets.messaging.AppConversations.pending_messages`

```python theme={null}
async pending_messages(self, thread_id: str, *, after: str) -> list[PendingMessage]
```

The thread's participant messages accepted after `after` and not yet carried into a turn.

The `accepted` records with `origin="client"` and `inbound_kind="message"` on
`thread_id` whose acceptance follows the `after` message, in acceptance order, each a
`PendingMessage`. Read-only and in-process (it reads the same thread index the turn
engine batches over), bounded by the thread's FIFO depth.

A body running inside a turn asks this — with `after` the turn's own lead `message_id` —
to learn whether a newer message is waiting, so it can yield (raise
`TurnSupersededError`) before an expensive or
irreversible step. Outside a turn there is nothing pending by definition. An unknown
`thread_id` reads as an empty list; a record already left `accepted` is not pending.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |
| `after` | `str` | — | — |

#### register\_target\_validator

`tai42_contract.app.facets.messaging.AppConversations.register_target_validator`

```python theme={null}
register_target_validator(
    self,
    target_kind: ConversationTargetKind,
    target_name: str,
    validator: TargetBindValidator,
) -> None
```

Register a bind validator for the `(target_kind, target_name)` the plugin OWNS.

A plugin calls this through the `tai42_app` handle when its module loads, naming the
one tool or agent it owns. A conversation route whose target RESOLVES to that owner (an
agent is its own name; a tool walks its parent-tool chain, so a preset inherits its base
tool's owner) consults the validator AFTER the target exists but BEFORE the route is
written; a validator returning any message lines refuses the creation with them (a 422),
so a defect the target carries is caught at bind, never deferred to run time. The
validator is passed the route's full create model and the target's candidate body.
Registering two validators for one `(target_kind, target_name)` raises loudly — a name
has one owner.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `target_kind` | `ConversationTargetKind` | — | — |
| `target_name` | `str` | — | — |
| `validator` | `TargetBindValidator` | — | — |

## AppExtensions

`tai42_contract.app.facets.execution.AppExtensions`

```python theme={null}
class AppExtensions(Protocol)
```

The tool-extension provider namespace (`app.extensions`).

### Members

#### extension

`tai42_contract.app.facets.execution.AppExtensions.extension`

```python theme={null}
extension(
    self,
    f: Callable[..., Any] | None = None,
    *,
    kind: ExtensionKind,
    name: str | None = None,
    requires_body_locality: bool = False,
    pauses: bool = False,
    declares_output_schema: bool = False,
) -> Callable[..., Any]
```

Register a tool-extension factory under `name` (default: the function's own name).

Usable bare or with arguments. `requires_body_locality` marks an extension whose wrapper only works
in the process running the tool body it wraps — e.g. a proxy layer that
routes the body's egress through a task-scoped contextvar, visible only
where the body executes. The flag is stored as registration metadata the
apply site reads to order a stacked combo: a locality-requiring
extension must bind INSIDE any execution-relocating extension
(`ExtensionKind.relocates_execution`), so its wrapper travels with the
body to the worker. Bound outside a relocating layer, the wrapper stays
behind in the submitting process and silently does not apply.

`pauses` marks an extension every branch of which can pause, whatever its base
declares (an extension that re-dispatches other tools and passes their park
through); see `AppTools.pauses`.

`declares_output_schema`: this extension declares the wrapped tool's output shape (its
JSON Schema), so a preset over a tool carrying it may not also set `output_schema`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `f` | `Callable[..., Any] \| None` | `None` | — |
| `kind` | `ExtensionKind` | — | — |
| `name` | `str \| None` | `None` | — |
| `requires_body_locality` | `bool` | `False` | — |
| `pauses` | `bool` | `False` | — |
| `declares_output_schema` | `bool` | `False` | — |

#### available\_extensions

`tai42_contract.app.facets.execution.AppExtensions.available_extensions`

```python theme={null}
available_extensions(self) -> list[dict[str, str | bool]]
```

List registered extensions as `[{"name", "kind", "multiple"}]`.

`multiple` says whether one tool may stack several extensions of that kind.

## AppHttp

`tai42_contract.app.facets.routing.AppHttp`

```python theme={null}
class AppHttp(Protocol)
```

The HTTP application facet: middleware, route registration, and mount introspection.

### Members

#### middleware

`tai42_contract.app.facets.routing.AppHttp.middleware`

```python theme={null}
middleware(self, cls: type[Any] | None = None, **options: Any) -> Callable[..., Any]
```

Register a middleware on the application.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `options` | `Any` | `{}` | — |

#### custom\_route

`tai42_contract.app.facets.routing.AppHttp.custom_route`

```python theme={null}
custom_route(
    self,
    path: str,
    methods: list[str],
    name: str | None = None,
    include_in_schema: bool = True,
    *,
    summary: str,
    tags: list[str],
    response_model: type[BaseModel] | None,
    request_model: type[BaseModel] | None = None,
    query_model: type[BaseModel] | None = None,
    authed: bool | None = None,
    destructive: bool = False,
    action: RouteAction | None = None,
    self_service: bool = False,
    any_authenticated: bool = False,
    pre_auth: bool = False,
    declared: DeclaredRouteMetadata | None = None,
    no_body_reason: str | None = None,
    enveloped: bool = True,
    success_media_types: Mapping[str, tuple[str, ...]] | None = None,
) -> Callable[[Callable[[Request], Awaitable[Response]]], Callable[[Request], Awaitable[Response]]]
```

Register a Starlette handler AND its self-describing route metadata.

The metadata is the single source of truth the OpenAPI 3.1 emitter and its
coverage gate consume, so every registration MUST describe itself:

* `summary` — a one-line operation summary (required, non-empty).
* `tags` — at least one OpenAPI tag grouping the route (required).
* `response_model` — the pydantic model (any `BaseModel`, `RootModel`
  included) describing the success body. Required — there is no default, so a
  route cannot silently omit it. By default the model is wrapped in the
  `{"data": ...}` success envelope; a route that answers a RAW top-level body
  passes `enveloped=False` (see below). `None` is legal ONLY together with a
  non-blank `no_body_reason`: the two states are mutually exclusive — a route
  declares a typed body OR a reasoned no-body, never both and never neither.
* `enveloped` — whether the JSON success body is wrapped in the
  `{"data": <response_model>}` envelope (the default, `True`) or is the
  model's schema DIRECTLY at the top level (`False`, a raw non-enveloped
  body). `enveloped=False` REQUIRES a `response_model`: an unwrapped body
  still needs a real model, so a bare `None` under it is a registration error.
* `no_body_reason` — the required-when-`response_model` is `None`
  justification for a route that serves no `{"data": <model>}` JSON body
  (a redirect, a raw/streaming/asset response, a vendor webhook 200, or a
  raw non-enveloped body the envelope emitter cannot describe). Passing it
  alongside a `response_model`, or omitting it when `response_model` is
  `None`, is a registration error.
* `success_media_types` — the media types each method's success body is
  published under, keyed by the route's upper-cased methods; each value is a
  non-empty tuple. A method left out (or `None`, the default) publishes
  `application/json`. A key outside the route's methods, an empty tuple, or
  a non-JSON type on an `enveloped=False` route is a registration error.
* `request_model` — the pydantic model of the request body; required for
  any route that reads a body, omitted (`None`) otherwise.
* `query_model` — the pydantic model whose fields are published as `in:
  query` parameters for ANY method, additive to `request_model`. A read
  door's `request_model` already emits as query, so this is the only way a
  WRITE-method door documents the query it reads at the edge; `None` (the
  default) publishes no query model.
* `authed` — whether the route requires the api key; emitted as the
  `security` requirement. `None` (the default) defers to the runtime:
  a core route resolves to `True`, a declared plugin route to the
  negation of its `tai-plugin.yml` `public` flag. Passing an explicit
  bool from a declared plugin route module is a registration error — the
  declaration is the single source of that decision.
* `destructive` — whether the route mutates in a way flagged as
  destructive (default `False`); emitted as `x-destructive`.
* `action` — the route's authorization character (a `RouteAction`);
  `None` (the default) lets the surface derive the grantable class from
  the HTTP methods.
* `self_service` — whether this route is a caller SELF-SERVICE surface
  (default `False`). A `True` route is carved into the default
  editor/viewer control-plane reach, so a non-admin role may invoke it even
  under an otherwise admin-gated prefix (an own-credential change under
  `/api/auth`). The seed derives the carve-in from every route declaring
  this, so the platform names no provider's route.
* `any_authenticated` — whether this route is reachable by ANY authenticated
  identity whatever its scopes and whatever the route table maps (an
  identity-introspection route); the base-tier jq still applies; an
  unauthenticated caller is denied 401. Requires the route to be authenticated.
* `pre_auth` — whether this route is a pre-authentication surface (login,
  recovery, claim exchange): presented credentials are NOT verified, so a stale
  credential can never lock a caller out of the door that replaces it; the route
  is public and no policy layer runs. Requires the route to be public. A declared
  plugin route passes either flag itself; a flag contradicting the route's
  publicness is a registration error.
* `declared` — the route's behavioral OpenAPI properties (a
  `DeclaredRouteMetadata`): its `reload_gated` / `reads_body` /
  error statuses / success status. A route in the `/api/*` spec surface
  declares these (the operations adapter passes its operation's metadata, a
  native handler passes its own); `None` (the default) records trivial
  defaults for a route outside the spec surface, whose behavioral metadata
  is never emitted. A route MAY also declare its own `max_body_bytes` (a
  per-route request body cap the app's request-body limit honours; default
  `None` defers to the app cap), its own `rate_limit_family` (the
  rate-limit family the door charges; default `None` defers to the
  path-derived family) and its family's `rate_limit_budget` (a
  `RateLimitBudget`; default `None` defers to the app-wide default).
  A `reload_gated` route answers the retriable reload `503` while a config
  reload holds the gate; the surface enforces it around the handler.

The handler's narrative docstring becomes the operation description.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `str` | — | — |
| `methods` | `list[str]` | — | — |
| `name` | `str \| None` | `None` | — |
| `include_in_schema` | `bool` | `True` | — |
| `summary` | `str` | — | — |
| `tags` | `list[str]` | — | — |
| `response_model` | `type[BaseModel] \| None` | — | — |
| `request_model` | `type[BaseModel] \| None` | `None` | — |
| `query_model` | `type[BaseModel] \| None` | `None` | — |
| `authed` | `bool \| None` | `None` | — |
| `destructive` | `bool` | `False` | — |
| `action` | `RouteAction \| None` | `None` | — |
| `self_service` | `bool` | `False` | — |
| `any_authenticated` | `bool` | `False` | — |
| `pre_auth` | `bool` | `False` | — |
| `declared` | `DeclaredRouteMetadata \| None` | `None` | — |
| `no_body_reason` | `str \| None` | `None` | — |
| `enveloped` | `bool` | `True` | — |
| `success_media_types` | `Mapping[str, tuple[str, ...]] \| None` | `None` | — |

#### use\_raw\_path\_key

`tai42_contract.app.facets.routing.AppHttp.use_raw_path_key`

```python theme={null}
use_raw_path_key(self, path_prefix: str) -> None
```

Match already-registered routes under `path_prefix` against the raw (undecoded) request path.

A path parameter whose values carry `/` (a state record's `{key}`, addressed as one
percent-encoded segment) stays ONE segment instead of splitting once the ASGI server has
decoded `%2F`; the matched parameters are decoded once after the match. Called AFTER the
routes are registered, over their shared prefix, so it covers a family of doors at one seam. A
no-op where no route table is served (the offline spec harness).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path_prefix` | `str` | — | — |

#### mount\_base

`tai42_contract.app.facets.routing.AppHttp.mount_base`

```python theme={null}
mount_base(self) -> str
```

The resolved absolute mount base of the declared plugin route module importing now.

`/api/` + the item's mount base, no trailing slash (e.g. `/api/channels/telegram`).

Callable ONLY while a declared plugin route module imports — the mount
binding is present then. A module captures this value at import for later
use (a startup hook building an external webhook URL, a login descriptor's
self-referential path) so a remapped base is followed instead of a
hardcoded default. Called with no binding present — a core or
operator-authored module — it raises: those modules own no declared mount.

#### hosted\_ui

`tai42_contract.app.facets.routing.AppHttp.hosted_ui`

```python theme={null}
hosted_ui(self) -> HostedUiPaths
```

The page addresses of the hosted UI, as the deployment declares them.

## AppInteractions

`tai42_contract.app.facets.messaging.AppInteractions`

```python theme={null}
class AppInteractions(Protocol)
```

The interactions namespace (`app.interactions`) — the `ask` facade and answer check.

### Members

#### check\_answer

`tai42_contract.app.facets.messaging.AppInteractions.check_answer`

```python theme={null}
check_answer(self, question: QuestionFormat, answer: Any) -> Any
```

Validate `answer` against `question` — the ONE answer check every door reaches.

`question` is a `QuestionFormat` (the answer
format plus its payload — no stored request needed). RETURNS the answer the consumer
receives when it conforms — identical to the input for every format but FORM, whose
fields hidden by their `visibleWhen` conditional (evaluated on the submitted values)
are removed, so every answer door records the same effective answer. Raises
`AnswerMismatchError` (carrying the failing field's
dotted path when the fault locates to one) otherwise. The answer door, the callback
door, a resumed run's `visit` and plugins all validate through this one callable so
every surface applies identical rules per format.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `question` | `QuestionFormat` | — | — |
| `answer` | `Any` | — | — |

#### form\_shape\_errors

`tai42_contract.app.facets.messaging.AppInteractions.form_shape_errors`

```python theme={null}
form_shape_errors(
    self,
    question: QuestionFormat,
    values: Mapping[str, Any],
    *,
    fields: Collection[str] | None = None,
    partial: bool = False,
) -> list[FormShapeError]
```

Every FORM field whose value in `values` breaks its declared shape — the ONE shape check.

`question` is a FORM `QuestionFormat`; the check runs
the same effective schema the answer door applies (per-send option lists, reaction-fed
choices typed only, fields hidden by their `visibleWhen` dropped) plus the platform date
constraints, and returns at most one `FormShapeError` per
field (the first broken shape, in schema order) carrying a typed kind, the bound it names
and the platform's plain sentence. `fields` restricts the check to the named top-level
properties (one step of a stepped form); `partial=True` is a mid-form check: nothing is
demanded (no `required` error) and an absent field is not checked. Pure — no store read.
A surface calls it inside the form before the submit leaves it; the answer door refuses a
FORM answer with the first error's sentence and field. Raises `ValueError` when
`question` is not a FORM carrying an object schema.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `question` | `QuestionFormat` | — | — |
| `values` | `Mapping[str, Any]` | — | — |
| `fields` | `Collection[str] \| None` | `None` | — |
| `partial` | `bool` | `False` | — |

#### question\_format

`tai42_contract.app.facets.messaging.AppInteractions.question_format`

```python theme={null}
question_format(
    self,
    answer_format: str,
    *,
    options: list[str] | None = None,
    schema: dict[str, Any] | None = None,
    data: dict[str, Any] | None = None,
    pages: list[dict[str, Any]] | None = None,
    reactions: dict[str, Any] | None = None,
) -> QuestionFormat
```

The answer-check view of an ask with these arguments (the parameter names are the `ask` tool's own).

The stored `format_payload` minus EXTERNAL's delivery keys (`url`, `verifier`), ready
for `check_answer`. Raises `ValueError` for an unknown format, an argument not valid
for the format, or a value of the wrong shape.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `answer_format` | `str` | — | — |
| `options` | `list[str] \| None` | `None` | — |
| `schema` | `dict[str, Any] \| None` | `None` | — |
| `data` | `dict[str, Any] \| None` | `None` | — |
| `pages` | `list[dict[str, Any]] \| None` | `None` | — |
| `reactions` | `dict[str, Any] \| None` | `None` | — |

#### react

`tai42_contract.app.facets.messaging.AppInteractions.react`

```python theme={null}
async react(
    self,
    interaction_id: str,
    event: FormReactionEvent,
    partial_values: dict[str, Any],
) -> dict[str, Any]
```

Run an OPEN reacting form's handler for `event` with the partial values — the ONE reaction seam.

A reacting form names a `reaction_tool` and declares its triggers in
`format_payload["reactions"]`. Every reaction transport (a channel callback, the in-app
door) routes one event and the values filled so far here: it asserts the interaction is an
open reacting form, type-validates `partial_values` against the stored schema, runs the
asker's handler through `run_tool` under the stored rebound identity with a deadline,
validates the returned FORM UPDATE (`values`/`errors` for declared fields,
`options` for option-bearing fields, `display` for declared slots), and returns it.
STATELESS: it never records an answer, resolves the interaction, or rewrites the request.
A handler that raises or misses the deadline surfaces LOUDLY, never a stale/silent value.
Raises a `FormReactionError` on a closed interaction, a
malformed request, or a handler failure; its `reason` is the door's sentence.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `interaction_id` | `str` | — | — |
| `event` | `FormReactionEvent` | — | — |
| `partial_values` | `dict[str, Any]` | — | — |

#### assert\_resume\_authorized

`tai42_contract.app.facets.messaging.AppInteractions.assert_resume_authorized`

```python theme={null}
async assert_resume_authorized(self, interaction_id: str) -> None
```

Authorise the caller to resume (or deliver an outcome for) `interaction_id` — or raise.

A driver's continuation face and cross-driver chain-delivery tool call this with the id
they are about to resume/deliver-to, BEFORE producing any outcome, because those tools are
dispatchable by name at the run-tool door and the MCP edge. Authorised only inside the
platform's own drive (resume, kill or give-up) of that run: it passes iff the ambient
run-authorization context names `interaction_id` directly (the resume origin), OR the
interaction's stored run delivery identity matches the ambient one (another interaction of
the same run), OR `interaction_id` is a chain key in the driven interaction's recorded
chain lineage (a cross-driver chain re-entry of a caller the driven run is nested under).
Raises `ParkResumeUnauthorizedError` for an external
caller (no origin), an id belonging to another run, or a chain key outside the lineage —
never a mere presence test. Raises `ParkRunTakenDownError`
when the ambient drive belongs to a run the platform has taken down.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `interaction_id` | `str` | — | — |

#### assert\_delivery\_authorized

`tai42_contract.app.facets.messaging.AppInteractions.assert_delivery_authorized`

```python theme={null}
assert_delivery_authorized(self, completion_id: str | None) -> None
```

Authorise a door delivery-address tool to fire for `completion_id` — or raise.

A door's out-of-band delivery address is a registered tool the platform's delivery ladder
fires; the tool calls this at entry with the payload's `completion_id` before delivering
anything. It passes iff the ambient delivery-fire context is set AND equals
`completion_id` — a `None` id and a call outside any fire never pass. Raises
`ParkDeliveryUnauthorizedError` otherwise, so a caller
naming the address tool directly at the run-tool door or the MCP edge delivers nothing.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `completion_id` | `str \| None` | — | — |

#### redelivery\_horizon\_seconds

`tai42_contract.app.facets.messaging.AppInteractions.redelivery_horizon_seconds`

```python theme={null}
redelivery_horizon_seconds(self) -> int
```

The platform's redelivery retention horizon in seconds.

The continuation-due record ages out at it and the reaper caps its redelivery backoff at
it, so no resume redelivery fires past it. A resuming driver derives its own
resolution-record retention from this value rather than a hard-coded guess.

#### callback\_url\_prefix

`tai42_contract.app.facets.messaging.AppInteractions.callback_url_prefix`

```python theme={null}
callback_url_prefix(self) -> str | None
```

The absolute URL prefix every callback URL this platform mints starts with.

`{public base}/api/interactions/callback/`; `None` when the deployment configures no
public base. A component that POSTs an answer to a stored callback URL pins it against this
prefix first.

#### visit

`tai42_contract.app.facets.messaging.AppInteractions.visit`

```python theme={null}
visit: Visit
```

The bound, `Visit`-typed shared-visit callable.

The ONE seam every door drives a parkable run through: it runs the cancel / resume / take /
start order once for every caller (checks everything before doing anything, cancels,
resumes or takes at most one action besides cancel, starts the target when nothing was
resumed, normalises what came back), and returns a
`VisitOutcome`. A door resolves its own jqs to plain
values and hands them in; the generic `list_parked` / `resume_parked` / `cancel_parked`
below are thin wrappers over this same seam.

#### settle\_visit\_claim

`tai42_contract.app.facets.messaging.AppInteractions.settle_visit_claim`

```python theme={null}
settle_visit_claim: SettleVisitClaim
```

The bound `SettleVisitClaim` read of a visit's claim.

Given the `VisitAct` of a resume or take claim whose
`committed` notice a door never saw, it returns the ids no longer open in the interactions
store. An empty result proves the claim did not commit; a returned id was resolved by some
door, and the read does not say which.

#### run\_answer

`tai42_contract.app.facets.messaging.AppInteractions.run_answer`

```python theme={null}
run_answer(self, outcome: VisitOutcome) -> RunAnswer
```

The ONE `RunAnswer` a run door hands back for a `VisitOutcome`.

Discriminated on `kind`: `result` carries the run's own value, `asks` the caller ask
entries the run parked with its re-park sentinel, `parked` the sentinel alone, `none`
nothing. Both the synchronous run-tool door and the background submit's parked record
shape a run through this ONE callable, so a poller of either door reads identical bytes.
It never reveals a wrapped secret — the sync door reveals those on its own `result` and
every recorder masks its own copy. An `asks`/`parked` outcome carrying no sentinel
raises `RuntimeError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `outcome` | `VisitOutcome` | — | — |

#### normalise\_started

`tai42_contract.app.facets.messaging.AppInteractions.normalise_started`

```python theme={null}
async normalise_started(self, value: Any) -> VisitOutcome
```

Classify a raw start return into a `started` `VisitOutcome` over the ambient subject.

The same normalisation `visit` applies to what its `start` returned — caller asks,
a re-park, or a final result — exposed for a door that already ran its start INSIDE its own
`visit` (a hook fire whose visit owns the run) and only needs the return classified,
so its record carries the same park answer both direct doors return.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `Any` | — | — |

#### list\_parked

`tai42_contract.app.facets.messaging.AppInteractions.list_parked`

```python theme={null}
async list_parked(self) -> list[ParkedEntry]
```

Every parked interaction on the current run's subject — the full parked entries.

Reads the ambient run's subject candidates and returns the union over its subject keys,
de-duplicated, each a `ParkedEntry` with its id, status
(`asking`/`running`/`finished`/`failed`) and the question/answer fields a
state-backed entry carries. The same rows a door-contract jq reads as `$parked`.

#### list\_parked\_for

`tai42_contract.app.facets.messaging.AppInteractions.list_parked_for`

```python theme={null}
async list_parked_for(self, context: StateContext | None) -> list[ParkedEntry]
```

Every parked interaction on `context`'s subject — the same entries as `list_parked`.

A parkable-driving door fetches this over its OWN
`StateContext` once and feeds the list to the door-contract
evaluator as `$parked`, keeping the contract evaluation a pure function of an injected
list rather than an ambient read. A `None` context has no subject and returns an empty
list.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `context` | `StateContext \| None` | — | — |

#### current\_fire\_identity

`tai42_contract.app.facets.messaging.AppInteractions.current_fire_identity`

```python theme={null}
current_fire_identity(self) -> tuple[str, str] | None
```

The ambient execution identity as the `(user_id, fingerprint)` pair a fire forwards, or `None`.

A background task tool dispatched from within a door fire forwards this pair onto its worker
job so the deferred fire re-binds the SAME authority; `None` when no identity (or no
per-mint fingerprint) is bound, so nothing is forwarded and the deferred fire fails closed on
any credential seam rather than under a substituted principal.

#### bound\_execution\_identity\_for\_fire

`tai42_contract.app.facets.messaging.AppInteractions.bound_execution_identity_for_fire`

```python theme={null}
bound_execution_identity_for_fire(self, execution_key: str, fingerprint: str) -> AbstractAsyncContextManager[Any]
```

An `async with` binding `execution_key`'s live-grant identity for a receiver-less door fire.

A scheduled fire has no live caller, so the door stores the firing identity (the execution
key's `user_id` and its per-mint `fingerprint`) at create and binds it here at fire, so a
run that async-parks can rebind its continuation and a `to="caller"` resume acts under the
same authority. Homed beside the door's other kit-reachable seams so a backend plugin binds a
scheduled fire's identity without importing the skeleton. Raises when the key no longer
carries authority — the fire fails closed, never under a substituted principal.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `execution_key` | `str` | — | — |
| `fingerprint` | `str` | — | — |

#### resume\_parked

`tai42_contract.app.facets.messaging.AppInteractions.resume_parked`

```python theme={null}
async resume_parked(self, interaction_id: str, payload: Any = ...) -> VisitOutcome
```

Resume a parked caller ask with `payload`, or TAKE its waiting outcome when omitted.

With `payload` given it resumes the `asking` caller ask `interaction_id` and returns
the resumed run's normalised outcome; with `payload` omitted it TAKES a `finished`
entry's waiting outcome (`kind="result"`) or re-raises a `failed` one as
`ParkableRunFailedError`. A live inline receiver, so the
resumed run's terminal is returned inline rather than delivered out of band.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `interaction_id` | `str` | — | — |
| `payload` | `Any` | `...` | — |

#### cancel\_parked

`tai42_contract.app.facets.messaging.AppInteractions.cancel_parked`

```python theme={null}
async cancel_parked(self, ids: list[str]) -> VisitOutcome
```

Kill the whole run of every parked interaction named in `ids` on the current run's subject.

Each id is torn down through the one teardown seam, which takes the whole run down: every open
ask of the run, nested runs included and the callers waiting on it; nothing of the run is
resumed and nothing is said to the person (the channel that delivered an ask releases what it
held for it, and a door that started the run is delivered `withdrawn` once); returns a
`VisitOutcome` naming the ids cancelled. An id outside
the run's own parked list raises `ParkedEntryGoneError`
with nothing cancelled.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `ids` | `list[str]` | — | — |

#### ask

`tai42_contract.app.facets.messaging.AppInteractions.ask`

```python theme={null}
ask: Ask
```

The bound, `Ask`-typed `ask` callable.

An in-process plugin asks a human without importing the skeleton:
`await tai42_app.interactions.ask(question, ..., mode="async",
expiry_at=...)`. The return shape is the `Ask` contract's:
`mode="sync"` returns an `AskAnswer`,
`mode="async"` returns a `SuspendedInteraction`. Its full call signature is the `Ask`
Protocol's, including the per-ask `on_mismatch` digression policy and
the `wording` catalogue a channel-delivered ask carries. A facade
EXPOSURE of the skeleton helper through the already-typed Protocol — no new
ask semantics.

## AppLifecycle

`tai42_contract.app.facets.runtime.AppLifecycle`

```python theme={null}
class AppLifecycle(Protocol)
```

Startup, shutdown, reload, and post-swap lifecycle hook registration.

### Members

#### on\_startup

`tai42_contract.app.facets.runtime.AppLifecycle.on_startup`

```python theme={null}
on_startup(self, func: Callable[[], Any]) -> Callable[[], Any]
```

Register `func` to run at process startup (usable as a decorator).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `func` | `Callable[[], Any]` | — | — |

#### on\_shutdown

`tai42_contract.app.facets.runtime.AppLifecycle.on_shutdown`

```python theme={null}
on_shutdown(self, func: Callable[[], Any]) -> Callable[[], Any]
```

Register `func` to run at process shutdown (usable as a decorator).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `func` | `Callable[[], Any]` | — | — |

#### on\_reload

`tai42_contract.app.facets.runtime.AppLifecycle.on_reload`

```python theme={null}
on_reload(self, func: Callable[[], Any]) -> Callable[[], Any]
```

Register a handler re-run after every in-place re-init (`reload_config`).

For example, dynamic tool loaders that `on_startup` ran once.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `func` | `Callable[[], Any]` | — | — |

#### on\_post\_swap

`tai42_contract.app.facets.runtime.AppLifecycle.on_post_swap`

```python theme={null}
on_post_swap(self, func: Callable[[], Any]) -> Callable[[], Any]
```

Register an establisher for a loop-affine background loop (a periodic poll or sweep).

Run on the real serving loop at boot and after every epoch swap — never on
the throwaway build-thread loop the per-epoch handlers run on — so the loop
it spawns attaches to the serving loop and retires with its generation.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `func` | `Callable[[], Any]` | — | — |

#### on\_fleet\_op\_applied

`tai42_contract.app.facets.runtime.AppLifecycle.on_fleet_op_applied`

```python theme={null}
on_fleet_op_applied(self, func: Callable[[FleetOpApplied], Any]) -> Callable[[FleetOpApplied], Any]
```

Register a handler fired after any worker-bus op applies in this process.

Also fired after the reconnect self-resync reload. The handler takes ONE argument — the
applied op with its declared effects (`FleetOpApplied`);
decide on `effects`, never on `op` (a query op declares none). Its `budget` is the
seconds remaining before the publisher's report cut, measured from this process's
receipt of the op; a post-apply obligation that cannot finish within it must raise.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `func` | `Callable[[FleetOpApplied], Any]` | — | — |

#### wait\_until\_ready

`tai42_contract.app.facets.runtime.AppLifecycle.wait_until_ready`

```python theme={null}
async wait_until_ready(self) -> None
```

Block until this process's first boot self-resync has completed.

That is the point at which the tool registry is fully built and stable for
the run. A backend runtime that forks a child (or otherwise consumes queued work)
per job awaits this before its work loop accepts anything: the boot
self-resync rebuilds the tool registry non-atomically, so a worker that
dequeued and forked mid-rebuild would run the job against a half-built
registry. The latch is one-way — it resolves once and stays resolved, so
a later bus reconnect (which re-runs the self-resync while the app is
already live) never un-readies the process.

## AppMedia

`tai42_contract.app.facets.media.AppMedia`

```python theme={null}
class AppMedia(Protocol)
```

The served-media ingestion namespace (`app.media`).

A channel adapter or the web upload door streams inbound bytes through the ONE
`ingest_media` chokepoint; the platform caps, sniffs, stores, and mints a served
reference, returning the typed `IngestedMedia`. The body is the skeleton's; this facet
is the contract the doors and the impl agree on.

### Members

#### ingest\_media

`tai42_contract.app.facets.media.AppMedia.ingest_media`

```python theme={null}
async ingest_media(
    self,
    *,
    source: AsyncIterator[bytes],
    kind_hint: InboundMediaKind | str | None,
    declared_mime: str | None,
    filename: str | None,
    declared_size: int | None,
    origin: MediaOrigin,
) -> IngestedMedia
```

Ingest one streamed inbound media, returning its served reference and metadata.

Reads `source` under the platform's per-kind byte cap (raising loudly on a cap crossing,
never truncating), sniffs the real type, agrees it against `declared_mime`, stores the
bytes by reference, and returns an `IngestedMedia` whose `item` carries the served
`{MEDIA_ROUTE_PREFIX}{media_id}` url. Raises a
`MediaIngestError` subclass on an over-cap /
disallowed-type / unfetchable / store-unavailable outcome — never a silent skip.

Two-phase (upload-then-attach) support rides `origin.message_id`: when it is `None` the
item is ingested PENDING (retained only for `MEDIA_INGEST_PENDING_TTL_SECONDS`, owned by
`(origin.channel_id, origin.participant_identity)`) so a door that receives the bytes
before the owning message exists (the web upload door) can bind it later with
`bind_media`; when it is set the item is bound at ingest to the record's retention
horizon (the vendor channels, which know the message id at fetch time).
`IngestedMedia.pending` reports which state resulted.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `source` | `AsyncIterator[bytes]` | — | — |
| `kind_hint` | `InboundMediaKind \| str \| None` | — | — |
| `declared_mime` | `str \| None` | — | — |
| `filename` | `str \| None` | — | — |
| `declared_size` | `int \| None` | — | — |
| `origin` | `MediaOrigin` | — | — |

#### bind\_media

`tai42_contract.app.facets.media.AppMedia.bind_media`

```python theme={null}
async bind_media(self, media_id: str, *, origin: MediaOrigin) -> IngestedMedia
```

Promote a PENDING ingested media to the owning conversation record's retention horizon.

Called when a message finally references a `media_id` ingested with no `origin.message_id`
(`origin.message_id` is REQUIRED here). Idempotent when the item is already bound to the
SAME message. Raises loudly, never silently:
`MediaNotFoundError` — one uniform error for an unknown,
an expired-pending, or a `media_id` NOT owned by the caller's
`(origin.channel_id, origin.participant_identity)` (no ownership oracle — the three cases
are indistinguishable to the caller);
`MediaAlreadyBoundError` — the item is already bound to a
DIFFERENT message. Returns the now-bound `IngestedMedia` (`pending == False`).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `media_id` | `str` | — | — |
| `origin` | `MediaOrigin` | — | — |

## AppMonitoring

`tai42_contract.app.facets.runtime.AppMonitoring`

```python theme={null}
class AppMonitoring(Protocol)
```

Registration and access for the process monitoring backend.

### Members

#### register\_monitoring

`tai42_contract.app.facets.runtime.AppMonitoring.register_monitoring`

```python theme={null}
register_monitoring(self, builder: Callable[..., Any] | None = None) -> Callable[..., Any]
```

Register the monitoring backend builder, or return a decorator when `builder` is omitted.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `builder` | `Callable[..., Any] \| None` | `None` | — |

#### active

`tai42_contract.app.facets.runtime.AppMonitoring.active`

```python theme={null}
active: Monitoring
```

The active monitoring backend (impl type behind the contract protocol).

## AppPresets

`tai42_contract.app.facets.authoring.AppPresets`

```python theme={null}
class AppPresets(Protocol)
```

The presets namespace (`app.presets`) — the typed view + the bind kernel.

`store` is the `PresetStore`-typed view over
`app.versioning.store` (`kind="preset"`). `bind` is the kernel BOTH tiers
(ephemeral and versioned) build their live tool through, so its typed-schema
behavior reaches both.

### Members

#### bind

`tai42_contract.app.facets.authoring.AppPresets.bind`

```python theme={null}
async bind(
    self,
    base_tool: str,
    fixed_kwargs: dict[str, Any],
    *,
    name: str,
    description: str = '',
    tags: list[str] | None = None,
    output_schema: dict[str, Any] | None = None,
) -> Tool
```

Return a FastMCP tool transform of `base_tool` as a new named tool.

Built in ONE `Tool.from_tool` call: each `fixed_kwargs` key is baked as
a HIDDEN, FIXED constant (removed from the exposed schema; a caller that
passes it is rejected — it cannot be overridden at runtime) while the
REMAINING arguments keep the base tool's real typed schema (names, types,
descriptions). `tags` sets the transformed tool's native tags. An
`output_schema` (an object JSON Schema) is baked into an agent base's
`response_format` (forcing structured output) or advertised + validated on
a plain tool base. `bind` is async because it must resolve the base
`Tool` object (via `app.tools.get_tool(base_tool)`) to feed the
transform.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `base_tool` | `str` | — | — |
| `fixed_kwargs` | `dict[str, Any]` | — | — |
| `name` | `str` | — | — |
| `description` | `str` | `''` | — |
| `tags` | `list[str] \| None` | `None` | — |
| `output_schema` | `dict[str, Any] \| None` | `None` | — |

#### create

`tai42_contract.app.facets.authoring.AppPresets.create`

```python theme={null}
async create(
    self,
    name: str,
    base_tool: str,
    description: str,
    fixed_kwargs: dict[str, Any],
    *,
    input_schema: dict[str, Any] | None = None,
    output_schema: dict[str, Any] | None = None,
    extensions: list[list[ExtensionElement]] | None = None,
    state_binding: StateBinding | None = None,
    tags: list[str] | None = None,
) -> dict[str, Any]
```

Create a versioned preset in-process and return its record view.

The in-process authoring seam beside the HTTP create door: it runs the same
content path (name pre-checks, combo/schema/bind validation, input-schema
support, the base tool's write validator, store write THEN register, and the
rebind fan-out) and returns the same record shape, so the two doors cannot drift.
A body its base tool cannot accept, a colliding name, or an `input_schema` over
a base tool with no registered support is a loud error that persists nothing. The
caller-authorization tier fence is OFF — the registration-tier fence authorizes a
request principal at the HTTP doors; an in-process caller authorizes its own callers
and passes only the base tools it is entitled to author — while every content check
stays on.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `base_tool` | `str` | — | — |
| `description` | `str` | — | — |
| `fixed_kwargs` | `dict[str, Any]` | — | — |
| `input_schema` | `dict[str, Any] \| None` | `None` | — |
| `output_schema` | `dict[str, Any] \| None` | `None` | — |
| `extensions` | `list[list[ExtensionElement]] \| None` | `None` | — |
| `state_binding` | `StateBinding \| None` | `None` | — |
| `tags` | `list[str] \| None` | `None` | — |

#### save\_version

`tai42_contract.app.facets.authoring.AppPresets.save_version`

```python theme={null}
async save_version(
    self,
    name: str,
    *,
    fixed_kwargs: dict[str, Any] | None = None,
    input_schema: dict[str, Any] | CarryForward | None = CARRY_FORWARD,
    output_schema: dict[str, Any] | None = None,
    output_schema_provided: bool = False,
    description: str | None = None,
    extensions: list[list[ExtensionElement]] | None = None,
    state_binding: StateBinding | CarryForward | None = CARRY_FORWARD,
    tags: list[str] | None = None,
) -> dict[str, Any]
```

Save a new version of an existing preset in-process and return the version row.

The in-process sibling of the HTTP save-version door, running the identical
content path and returning the same shape. Omitted fields carry the active
value forward (`input_schema` via the `CARRY_FORWARD` sentinel;
`output_schema` only when `output_schema_provided` is `True`). A body that
cannot bind is a loud error that commits nothing; the tier fence is OFF for the
reason `create` states.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `fixed_kwargs` | `dict[str, Any] \| None` | `None` | — |
| `input_schema` | `dict[str, Any] \| CarryForward \| None` | `CARRY_FORWARD` | — |
| `output_schema` | `dict[str, Any] \| None` | `None` | — |
| `output_schema_provided` | `bool` | `False` | — |
| `description` | `str \| None` | `None` | — |
| `extensions` | `list[list[ExtensionElement]] \| None` | `None` | — |
| `state_binding` | `StateBinding \| CarryForward \| None` | `CARRY_FORWARD` | — |
| `tags` | `list[str] \| None` | `None` | — |

#### register\_write\_validator

`tai42_contract.app.facets.authoring.AppPresets.register_write_validator`

```python theme={null}
register_write_validator(self, base_tool: str, validator: PresetWriteValidator) -> None
```

Register the write validator for `base_tool` (one per base tool; duplicate registration raises).

A base-tool plugin calls this through the `tai42_app` handle when its tool
module loads. The validator runs on every write that persists a body —
create / save-version / rollback — and in the dry-run `validate` verdict,
so a body its base tool cannot accept is a loud 400 that never persists. A
base tool with no registered validator gets no extra check.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `base_tool` | `str` | — | — |
| `validator` | `PresetWriteValidator` | — | — |

#### register\_input\_schema\_support

`tai42_contract.app.facets.authoring.AppPresets.register_input_schema_support`

```python theme={null}
register_input_schema_support(self, base_tool: str, support: PresetInputSchemaSupport) -> None
```

Declare that `base_tool` ACCEPTS a per-preset input schema (one per base tool; duplicate raises).

A base-tool plugin calls this through the `tai42_app` handle when its tool
module loads. A preset that sets an `input_schema` over a base tool with no
registered support is a loud authoring error at the shared preset-authoring
chokepoint, never a silently-ignored schema.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `base_tool` | `str` | — | — |
| `support` | `PresetInputSchemaSupport` | — | — |

#### input\_schema\_support

`tai42_contract.app.facets.authoring.AppPresets.input_schema_support`

```python theme={null}
input_schema_support(self, base_tool: str) -> PresetInputSchemaSupport | None
```

The input-schema support `base_tool` declared, or `None` if it declared none.

When `None`, the base tool's typed schema is fixed.

**Parameters**

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

#### register\_registration\_tier

`tai42_contract.app.facets.authoring.AppPresets.register_registration_tier`

```python theme={null}
register_registration_tier(self, base_tool: str, tier: RouteAction) -> None
```

Declare the authz tier required to author a preset over `base_tool` (one per base tool).

Governs create/save/rollback/rename; duplicate registration raises.
Default authoring is the presets' own `write` action; a base tool with no
declaration keeps that default. A base tool declaring `fenced` requires the
admin fence to author a preset over it. The shared preset-authoring chokepoint
reads this and enforces it BEFORE any store write on every authoring door.

**Parameters**

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

#### registration\_tier

`tai42_contract.app.facets.authoring.AppPresets.registration_tier`

```python theme={null}
registration_tier(self, base_tool: str) -> RouteAction | None
```

The authoring authz tier `base_tool` declared, or `None` if it declared none.

When `None`, authoring keeps the presets' default `write` action.

**Parameters**

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

#### get\_active\_versioned\_body

`tai42_contract.app.facets.authoring.AppPresets.get_active_versioned_body`

```python theme={null}
async get_active_versioned_body(self, name: str) -> tuple[int, PresetBody]
```

One preset's active `(version, body)` read TOGETHER in one query.

The version-aware sibling of `store.get_active_body`: it captures the active version
pointer and the body it points at atomically, so a consumer that needs the version beside
the body never risks a skewed second read across a concurrent activation. Raises
`PresetNotFoundError` for an unknown preset.

**Parameters**

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

#### used\_by

`tai42_contract.app.facets.authoring.AppPresets.used_by`

```python theme={null}
async used_by(self, name: str) -> list[str]
```

The other presets whose active bodies compose preset `name` as a tool, sorted.

Computed over the active preset population (a body's composed tool names intersected with
the population, self excluded), so it answers "which saved presets depend on this one" for a
rename/delete dependents pass. Raises
`PresetNotFoundError` for a name that is not a known
preset.

**Parameters**

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

#### register\_seed

`tai42_contract.app.facets.authoring.AppPresets.register_seed`

```python theme={null}
register_seed(self, seed: PresetSeed) -> None
```

Declare a default preset the platform seeds at import time.

A plugin calls this through the `tai42_app` handle when its module loads.
The declared seeds are applied by the startup/reload seed applier — created
when absent, a preset already present left untouched. Declaring two seeds
under the same `name` raises loudly — a silent overwrite could drop one
plugin's default under another's.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `seed` | `PresetSeed` | — | — |

#### store

`tai42_contract.app.facets.authoring.AppPresets.store`

```python theme={null}
store: PresetStore
```

The typed preset view over `app.versioning.store` (`kind="preset"`).

## AppSandboxes

`tai42_contract.app.facets.execution.AppSandboxes`

```python theme={null}
class AppSandboxes(Protocol)
```

The sandbox-provider namespace (`app.sandboxes`).

### Members

#### register\_sandbox

`tai42_contract.app.facets.execution.AppSandboxes.register_sandbox`

```python theme={null}
register_sandbox(self, cls: type[Sandbox]) -> type[Sandbox]
```

Register the `Sandbox` provider (decorator form, returning the class unchanged).

One provider backs the slot; a second registration is a conflict the runtime rejects loudly.

#### sandbox

`tai42_contract.app.facets.execution.AppSandboxes.sandbox`

```python theme={null}
sandbox: Sandbox | None
```

The registered provider, or `None` — status/introspection ONLY.

Never gate execution on this nullable read; acquire through `require_sandbox`, the every-door
guarantee (a `None` property is how per-consumer checks drift).

#### require\_sandbox

`tai42_contract.app.facets.execution.AppSandboxes.require_sandbox`

```python theme={null}
require_sandbox(self) -> Sandbox
```

Return the registered provider from the ONE raising acquisition chokepoint.

Raise `SandboxUnavailableError` (naming `TAI_MCP_SANDBOX` and
`sandbox_module`) when none is registered. EVERY consumer acquires through here.

#### sandbox\_policy

`tai42_contract.app.facets.execution.AppSandboxes.sandbox_policy`

```python theme={null}
sandbox_policy(self) -> SandboxPolicy
```

Return the skeleton-resolved `SandboxPolicy`.

This is the plugin-reachable READ of the SAME policy the skeleton binds to the kit at the
session-create chokepoint.

Available REGARDLESS of whether a provider is registered (it reads operator
config, not a provider). Mirrors the `ask` / `resolve_connection_auth`
facade accessors that let an in-process plugin read a skeleton-resolved value
without importing the skeleton; a consumer building a policied spec reads the
network default and `scrub_transcript` here. Implemented in the skeleton,
which resolves the policy once and returns the SAME value it binds to the kit.

## AppStates

`tai42_contract.app.facets.states.AppStates`

```python theme={null}
class AppStates(Protocol)
```

The subject-keyed state store namespace (`app.states`).

The door-agnostic contract every door and tool reads and writes a subject's document through.
The store takes a full `StateSubject` and refuses
anything less; subject resolution happens once per door, never here. Every write
door supplies a `WriteOrigin` carrying only what a
consumer knows — the platform completes it (`door`/`actor`/`turn_id`) at this
chokepoint, so the audit ledger is never optional or forgeable. While the `states`
component's database is unbound every method raises
`StatesNotConfiguredError` (501), never an empty read.

### Members

#### list\_declarations

`tai42_contract.app.facets.states.AppStates.list_declarations`

```python theme={null}
async list_declarations(self) -> list[StateDeclaration]
```

Every declared state.

#### get\_declaration

`tai42_contract.app.facets.states.AppStates.get_declaration`

```python theme={null}
async get_declaration(self, name: str) -> StateDeclaration | None
```

The declaration named `name`, or `None` when none is declared.

**Parameters**

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

#### put\_declaration

`tai42_contract.app.facets.states.AppStates.put_declaration`

```python theme={null}
async put_declaration(self, decl: StateDeclaration) -> StateDeclarationSaved
```

Declare or re-declare a state and return the stored declaration with the held saves it was accepted beside.

An additive re-declare (new optional fields, new subject kinds) is applied in
place; a change that would remove or narrow a field while records exist raises
`NonAdditiveRedeclareError` (erase the records
first), and removing a subject kind still present in records raises
`DeclarationInUseError`. Never a silent overwrite.
The state's pending saves are applied first; a save held by a failed save counts as
records present, so a re-declare that would refuse its document or remove a kind it
writes raises `DeclarationInUseError`, and an accepted one
names it in `held`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `decl` | `StateDeclaration` | — | — |

#### delete\_declaration

`tai42_contract.app.facets.states.AppStates.delete_declaration`

```python theme={null}
async delete_declaration(self, name: str) -> None
```

Delete a state with its records and attachments.

Raises `DeclarationInUseError` when a consumer still binds it.

**Parameters**

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

#### stats

`tai42_contract.app.facets.states.AppStates.stats`

```python theme={null}
async stats(self, name: str) -> dict[str, Any]
```

Counts for a state — records, subjects by kind, consumers — for the listing.

Counted over committed records; `held` lists the saves held by a failed save that the
counts do not include (each a `HeldPendingSave` dump).

**Parameters**

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

#### list\_templates

`tai42_contract.app.facets.states.AppStates.list_templates`

```python theme={null}
async list_templates(self) -> list[StateTemplateDocument]
```

Every stored platform template document.

#### get\_template

`tai42_contract.app.facets.states.AppStates.get_template`

```python theme={null}
async get_template(self, name: str) -> StateTemplateDocument | None
```

The template document named `name`, or `None` when none is stored.

The read a consumer's own sibling document validates against.

**Parameters**

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

#### put\_template

`tai42_contract.app.facets.states.AppStates.put_template`

```python theme={null}
async put_template(self, doc: StateTemplateDocument, *, replace: bool) -> StateTemplateDocument
```

Store a template document and return it (`replace` required to overwrite an existing name).

Runs every registered attach validator over each live attachment before the write,
so a consumer's data-dependent check still fires here; a raise leaves the stored
document untouched. Overwriting an existing name without `replace` raises
`TemplateExistsError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `doc` | `StateTemplateDocument` | — | — |
| `replace` | `bool` | — | — |

#### delete\_template

`tai42_contract.app.facets.states.AppStates.delete_template`

```python theme={null}
async delete_template(self, name: str) -> None
```

Delete a template document.

Raises `TemplateInUseError` while it is still attached.

**Parameters**

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

#### get\_rendered\_template

`tai42_contract.app.facets.states.AppStates.get_rendered_template`

```python theme={null}
async get_rendered_template(self, name: str) -> RenderedStateTemplate | None
```

The stored template `name` rendered — every body as jq text, the input programs ordered.

`None` when no such template is stored. A body that cannot be rendered raises
`TemplateValidationError` naming the template.

**Parameters**

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

#### rendered\_attachments

`tai42_contract.app.facets.states.AppStates.rendered_attachments`

```python theme={null}
async rendered_attachments(self, state: str) -> list[RenderedAttachment]
```

Every attachment on `state` with its rendered template, ordered by template name.

Raises `StateNotFoundError` for an undeclared state.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |

#### render\_template

`tai42_contract.app.facets.states.AppStates.render_template`

```python theme={null}
async render_template(self, doc: StateTemplateDocument) -> RenderedStateTemplate
```

Render a candidate template document that is not stored (its `version` is `"candidate"`).

Validates the document as a store would; a refusal raises
`TemplateValidationError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `doc` | `StateTemplateDocument` | — | — |

#### resolve\_template\_jq

`tai42_contract.app.facets.states.AppStates.resolve_template_jq`

```python theme={null}
async resolve_template_jq(
    self,
    state: str,
    name: str,
    *,
    purpose: Literal['input', 'update'],
    declared: Collection[str] = (),
) -> ResolvedTemplateJq
```

Resolve the `template_jq` reference `name` on `state` to the program a `purpose` call would run.

`<template>.<name>` resolves to that template's program; an unqualified `name` to the one
template that declares it across every attachment on the state. `declared` names templates
a caller is about to attach: each one not attached yet is resolved as if attached at
`[<template>]`. A template not attached (nor declared), or no such program, raises
`StateNotFoundError`; a name two templates declare, or a
program whose purpose is not `purpose`, raises
`ValueValidationError`. The rule every `template_jq` door
evaluates and applies by, so a reference accepted here resolves the same way at run time.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `name` | `str` | — | — |
| `purpose` | `Literal['input', 'update']` | — | — |
| `declared` | `Collection[str]` | `()` | — |

#### resolve\_template\_jq\_batch

`tai42_contract.app.facets.states.AppStates.resolve_template_jq_batch`

```python theme={null}
async resolve_template_jq_batch(self, refs: Sequence[TemplateJqReference]) -> list[ResolvedTemplateJq | StateNotFoundError | ValueValidationError]
```

Resolve every reference in `refs` in one call, each by `resolve_template_jq`'s rules.

Returns one item per reference, in order: its resolution, or the
`StateNotFoundError` /
`ValueValidationError` `resolve_template_jq` raises for
it, with the same message, so one refused reference never hides the others' verdicts. One
statement reads every named state's declaration version, and each reference resolves against
its state's catalog at that version; a write that lands on a state during the call can make
any reference on that state read the catalog's current rows and resolve against the newer
version. Any other failure raises for the whole call.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `refs` | `Sequence[TemplateJqReference]` | — | — |

#### resolve\_subject

`tai42_contract.app.facets.states.AppStates.resolve_subject`

```python theme={null}
async resolve_subject(self, state: str, ref: str | Mapping[str, Any] | None) -> StateSubject
```

Resolve a subject reference for `state` into a full `StateSubject`.

A mapping with both `target_kind` and `target_name` is the full subject; a `{kind, key}`
mapping takes its target from the ambient `context`; a key string takes the state's
`default_subject_kind` and the ambient target; `None` takes the ambient candidate for
the state's `default_subject_kind`. A reference that cannot be resolved — one target field
without the other, no ambient context where one is needed, a blank key, no ambient
candidate, a malformed mapping, any other shape — raises
`SubjectRefusedError` naming the rule; an undeclared state
raises `StateNotFoundError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `ref` | `str \| Mapping[str, Any] \| None` | — | — |

#### list\_attachments

`tai42_contract.app.facets.states.AppStates.list_attachments`

```python theme={null}
async list_attachments(self, state: str | None = None, *, template: str | None = None) -> list[dict[str, Any]]
```

Attachment rows filtered by `state`, by `template`, or every attachment when both are `None`.

What the attachments listing and the Consumers tab read. Each row carries `state`,
`template`, `path`, `parameters` and `declarations`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str \| None` | `None` | — |
| `template` | `str \| None` | `None` | — |

#### attach

`tai42_contract.app.facets.states.AppStates.attach`

```python theme={null}
async attach(self, state: str, template: str, body: AttachBody) -> list[HeldPendingSave]
```

Attach `template` on `state` at `body.path`, recomposing the effective schema in one transaction.

Stores the resolved parameters and declarations. Runs every registered attach validator before the write; a
raise refuses the door with the validator's message. Overlapping fragments raise
`AttachConflictError`. Returns the saves held by a failed save
whose subjects the validators and reconcilers read over their committed records.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `template` | `str` | — | — |
| `body` | `AttachBody` | — | — |

#### update\_attachment\_declarations

`tai42_contract.app.facets.states.AppStates.update_attachment_declarations`

```python theme={null}
async update_attachment_declarations(
    self,
    state: str,
    template: str,
    declarations: dict[str, Any],
    *,
    options: dict[str, Any] | None = None,
) -> list[HeldPendingSave]
```

Replace an attachment's declaration values, recomposing the effective schema before the write.

Re-runs every registered attach validator and reconciler before the write.
`options` is a per-operation directive bag passed to the reconcilers for THIS
operation only, never stored or served back (`None` is an empty bag). Returns the saves
held by a failed save whose subjects were read over their committed records.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `template` | `str` | — | — |
| `declarations` | `dict[str, Any]` | — | — |
| `options` | `dict[str, Any] \| None` | `None` | — |

#### detach

`tai42_contract.app.facets.states.AppStates.detach`

```python theme={null}
async detach(self, state: str, template: str) -> None
```

Remove an attachment and recompose the state's effective schema.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `template` | `str` | — | — |

#### read

`tai42_contract.app.facets.states.AppStates.read`

```python theme={null}
async read(self, state: str, subject: StateSubject) -> StateRecord | None
```

The record for `subject` (resolving a fold to its canonical subject), or `None` when none exists.

An unknown person or a target mismatch is a refusal, never an empty document.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `subject` | `StateSubject` | — | — |

#### replace

`tai42_contract.app.facets.states.AppStates.replace`

```python theme={null}
async replace(
    self,
    state: str,
    subject: StateSubject,
    data: dict[str, Any],
    *,
    origin: WriteOrigin,
) -> StateRecord
```

Replace `subject`'s whole document with `data` and return the new record.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `subject` | `StateSubject` | — | — |
| `data` | `dict[str, Any]` | — | — |
| `origin` | `WriteOrigin` | — | — |

#### merge

`tai42_contract.app.facets.states.AppStates.merge`

```python theme={null}
async merge(
    self,
    state: str,
    subject: StateSubject,
    patch: dict[str, Any],
    *,
    origin: WriteOrigin,
) -> StateRecord
```

Shallow top-level merge `patch` into `subject`'s document and return the new record.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `subject` | `StateSubject` | — | — |
| `patch` | `dict[str, Any]` | — | — |
| `origin` | `WriteOrigin` | — | — |

#### apply

`tai42_contract.app.facets.states.AppStates.apply`

```python theme={null}
async apply(
    self,
    state: str,
    subject: StateSubject,
    ops: list[dict[str, Any]],
    *,
    op_id: str | None,
    origin: WriteOrigin,
) -> ApplyResult
```

Apply an op batch to `subject`'s document under the effective schema.

Refuses a whole-path write over a `composing` path
(`RegimeViolationError`) before the ledger insert,
stamps `_trace` under a traced attachment, and records one `state_writes` row with
the touched paths and the completed origin. A replayed `op_id` returns
`applied=False` without re-writing; guarded ops land in `skipped`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `subject` | `StateSubject` | — | — |
| `ops` | `list[dict[str, Any]]` | — | — |
| `op_id` | `str \| None` | — | — |
| `origin` | `WriteOrigin` | — | — |

#### eval\_template\_jq

`tai42_contract.app.facets.states.AppStates.eval_template_jq`

```python theme={null}
async eval_template_jq(self, state: str, subject: StateSubject, name: str, params: dict[str, Any]) -> TemplateJqResult
```

Evaluate an `input`-purpose `template_jq` program `name` for `subject` and return its value.

The program's jq runs over the subject's record, `params` supplying
its declared parameters. `name` resolves across the state's attached templates
(unqualified → the declaring template; `<attachment>.<name>` → that attachment's
template). An unknown name is a `StateNotFoundError`; an
ambiguous unqualified name, an `update`-purpose name, an undeclared param or an
evaluation failure is a `ValueValidationError`. A read;
no write is recorded.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `subject` | `StateSubject` | — | — |
| `name` | `str` | — | — |
| `params` | `dict[str, Any]` | — | — |

#### apply\_template\_jq

`tai42_contract.app.facets.states.AppStates.apply_template_jq`

```python theme={null}
async apply_template_jq(
    self,
    state: str,
    subject: StateSubject,
    name: str,
    input_: Any,
    *,
    op_id: str | None,
    origin: WriteOrigin,
) -> TemplateJqApplyResult
```

Apply an `update`-purpose `template_jq` program `name` to `subject`.

Its jq maps the record subtree (its `.`) with `$input` bound to a template-relative op
batch, rebased under the attachment path and applied through the same chokepoint as
`apply` — so regimes, the
composing-shape guard, trace stamping and `op_id` idempotency all hold. `name`
resolves as for `eval_template_jq`. An unknown name is a
`StateNotFoundError`; an ambiguous unqualified name, an
`input`-purpose name, an evaluation failure or a wrong-shaped return is a
`ValueValidationError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `subject` | `StateSubject` | — | — |
| `name` | `str` | — | — |
| `input_` | `Any` | — | — |
| `op_id` | `str \| None` | — | — |
| `origin` | `WriteOrigin` | — | — |

#### apply\_batch

`tai42_contract.app.facets.states.AppStates.apply_batch`

```python theme={null}
async apply_batch(self, writes: list[StateBatchWrite]) -> list[ApplyResult]
```

Apply an ordered write set as ONE transaction, returning an `ApplyResult` per item in order.

Each `StateBatchWrite` is dispatched by its shape — an
`ops` batch through `apply`, a `template_jq` program through
`apply_template_jq` (its outcome mapped onto the item's `ApplyResult`) — over the
SAME store transaction, so items on one subject read each other's uncommitted writes in
order. Any item that raises rolls the WHOLE batch back and propagates loudly: no partial
write survives. `op_id` idempotency holds per item (a replayed key returns
`applied=False` without re-writing while its siblings land). The transaction's connection
stays hidden behind this seam — a door passes only the write set, never threads a
connection. An empty list is a no-op returning `[]`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `writes` | `list[StateBatchWrite]` | — | — |

#### open\_unit

`tai42_contract.app.facets.states.AppStates.open_unit`

```python theme={null}
open_unit(self) -> AbstractAsyncContextManager[StateUnit]
```

Open a unit of work over the states facet, bound to the caller's scope for the `async with` block.

Yields a `StateUnit` the caller stages writes against; while
the block is open the unit is the ambient unit every facet read of a staged subject is
served from (read-your-writes within the scope, the store's committed document to every
other scope). The caller `commit`s or `discard`s the unit; a unit left unresolved when
the block exits (a clean exit or a raised exception) is discarded at teardown and the
discard is logged. Nested runs join the outermost unit through `StateUnit.savepoint`.

#### erase

`tai42_contract.app.facets.states.AppStates.erase`

```python theme={null}
async erase(self, state: str, subject: StateSubject, *, origin: WriteOrigin) -> None
```

Erase `subject`'s record, recording the write.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `subject` | `StateSubject` | — | — |
| `origin` | `WriteOrigin` | — | — |

#### fold

`tai42_contract.app.facets.states.AppStates.fold`

```python theme={null}
async fold(
    self,
    state: str,
    subject: StateSubject,
    into: StateSubject,
    mode: str,
    *,
    origin: WriteOrigin,
) -> dict[str, Any]
```

Fold `subject` into `into` and return the resulting canonical document.

`mode` decides how the documents combine. A self-fold, a cycle, a conflicting re-fold,
or a merge whose result fails the schema raises
`SubjectFoldError`; a retried fold to the same target is a quiet no-op.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `subject` | `StateSubject` | — | — |
| `into` | `StateSubject` | — | — |
| `mode` | `str` | — | — |
| `origin` | `WriteOrigin` | — | — |

#### list\_subjects

`tai42_contract.app.facets.states.AppStates.list_subjects`

```python theme={null}
async list_subjects(
    self,
    state: str,
    *,
    kind: str | None = None,
    limit: int | None = None,
    cursor: str | None = None,
) -> dict[str, Any]
```

A keyset page of subjects for `state` (optionally one `kind`).

`{"subjects": [...], "next_cursor": <cursor|None>, "held": [...]}` — served over committed
records; `held` lists the saves held by a failed save whose subjects show their last
applied data (each a `HeldPendingSave` dump).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `kind` | `str \| None` | `None` | — |
| `limit` | `int \| None` | `None` | — |
| `cursor` | `str \| None` | `None` | — |

#### search

`tai42_contract.app.facets.states.AppStates.search`

```python theme={null}
async search(
    self,
    state: str,
    filters: dict[str, Any],
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> dict[str, Any]
```

A keyset page of records whose document contains `filters`.

`{"matches": [...], "next_cursor": <cursor|None>, "held": [...]}` — `held` as for
`list_subjects`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `filters` | `dict[str, Any]` | — | — |
| `limit` | `int \| None` | `None` | — |
| `cursor` | `str \| None` | `None` | — |

#### validate\_record

`tai42_contract.app.facets.states.AppStates.validate_record`

```python theme={null}
async validate_record(self, state: str, data: dict[str, Any]) -> RecordValidation
```

Check `data` against `state`'s effective schema exactly as a write would, without storing it.

Returns a `RecordValidation`: `fits` with EVERY reason it
does not (ordered by JSON path), never only the first. A misfit is a returned answer, not a
raise. A non-object `data` is a `ValueValidationError`; an
undeclared `state` is a `StateNotFoundError`; an effective
schema carrying an unresolvable `$ref` raises
`ValueValidationError` loudly.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `data` | `dict[str, Any]` | — | — |

#### check\_records

`tai42_contract.app.facets.states.AppStates.check_records`

```python theme={null}
async check_records(
    self,
    state: str,
    *,
    kind: str | None = None,
    limit: int | None = None,
    cursor: str | None = None,
) -> RecordCheckPage
```

One keyset page of `state`'s stored records checked against its current effective schema.

Pages like `list_subjects` (optionally one `kind`): `checked` is how many records
the page read and `items` are ONLY those that do not fit, each with every reason. `held`
names the saves held by a failed pending save whose subjects were skipped. An undeclared
`state` is a `StateNotFoundError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `kind` | `str \| None` | `None` | — |
| `limit` | `int \| None` | `None` | — |
| `cursor` | `str \| None` | `None` | — |

#### writes

`tai42_contract.app.facets.states.AppStates.writes`

```python theme={null}
async writes(
    self,
    state: str,
    subject: StateSubject,
    *,
    limit: int | None = None,
    cursor: str | None = None,
) -> WritesPage
```

One keyset page of the audit trail for `subject`, newest first.

The `items` (each a write with its completed origin and touched paths) plus the
`next_cursor` that pages the trail like `list_subjects`/`search` page
theirs (the last row's id when the page is full, else `None`).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |
| `subject` | `StateSubject` | — | — |
| `limit` | `int \| None` | `None` | — |
| `cursor` | `str \| None` | `None` | — |

#### prune\_expired

`tai42_contract.app.facets.states.AppStates.prune_expired`

```python theme={null}
async prune_expired(self) -> PruneResult
```

Delete records past their state's `retention_days` and return the per-state deletion counts.

A subject held by a failed pending save keeps its record; the held saves are named in
`held`.

#### context

`tai42_contract.app.facets.states.AppStates.context`

```python theme={null}
context(self) -> StateContext | None
```

The ambient `StateContext` the current door deposited.

`None` outside a door (an `api` write completes from the request principal instead).

#### register\_consumer\_lister

`tai42_contract.app.facets.states.AppStates.register_consumer_lister`

```python theme={null}
register_consumer_lister(self, kind: str, lister: ConsumerLister) -> None
```

Register a lister for consumer `kind` (flow / hook / schedule / agent).

A plugin calls this through the `tai42_app` handle when its module loads;
`consumers` unions every registered lister. Registering two listers for one
kind raises loudly.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `str` | — | — |
| `lister` | `ConsumerLister` | — | — |

#### consumers

`tai42_contract.app.facets.states.AppStates.consumers`

```python theme={null}
async consumers(self, state: str) -> list[ConsumerRow]
```

Everything that binds `state` — the union of every registered consumer lister — for the Consumers tab.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `str` | — | — |

#### register\_template\_seed

`tai42_contract.app.facets.states.AppStates.register_template_seed`

```python theme={null}
register_template_seed(self, doc: StateTemplateDocument) -> None
```

Declare a platform template document the platform seeds at import time.

A plugin calls this through the `tai42_app` handle when its module loads. The
startup/reload seed applier creates it when absent and leaves a template already
present untouched. Declaring two seeds under one name raises loudly.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `doc` | `StateTemplateDocument` | — | — |

#### register\_attach\_validator

`tai42_contract.app.facets.states.AppStates.register_attach_validator`

```python theme={null}
register_attach_validator(self, validator: AttachValidator) -> None
```

Register a data-dependent attach validator.

A plugin calls this through the `tai42_app` handle when its module loads. The
validator receives the state name, the template document, an attachment's declaration
values, and the state's effective schema, and RAISES to refuse; it runs before every `attach`,
`update_attachment_declarations` and `put_template(replace=True)` write, so a
consumer's checks fire at the platform's declarations doors, the States page
included.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `validator` | `AttachValidator` | — | — |

#### register\_attach\_reconciler

`tai42_contract.app.facets.states.AppStates.register_attach_reconciler`

```python theme={null}
register_attach_reconciler(self, reconciler: AttachReconciler) -> None
```

Register a pre-write attach reconciler.

A plugin calls this through the `tai42_app` handle when its module loads. The
reconciler receives a `AttachReconcileContext` — the
template, the operation, the previous and new declarations, the attach options, and a
record door bound to the state — inside every `attach` and
`update_attachment_declarations` write, after the validators and before the write. It
RAISES to refuse the attach (naming the records the new declarations orphan) or
writes resolutions through the context's record door and returns, letting the attach
commit with those writes.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `reconciler` | `AttachReconciler` | — | — |

## AppStorage

`tai42_contract.app.facets.execution.AppStorage`

```python theme={null}
class AppStorage(Protocol)
```

The storage-provider namespace (`app.storage`).

### Members

#### register\_storage

`tai42_contract.app.facets.execution.AppStorage.register_storage`

```python theme={null}
register_storage(self, cls: type[Storage] | None = None) -> Callable[[type[Storage]], type[Storage]] | type[Storage]
```

Register the `Storage` provider; usable bare or as a decorator factory.

#### resource\_manager

`tai42_contract.app.facets.execution.AppStorage.resource_manager`

```python theme={null}
resource_manager: Any
```

The active resource manager (impl type; loads/renders content over storage).

#### resolve\_image

`tai42_contract.app.facets.execution.AppStorage.resolve_image`

```python theme={null}
async resolve_image(self, source: str | bytes) -> ImageReference
```

Resolve a stored id, a data URI, raw bytes or a public URL to an addressable image with its asserted mime.

A non-image or a path outside the store raises `ValueError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `source` | `str \| bytes` | — | — |

#### on\_template\_evicted

`tai42_contract.app.facets.execution.AppStorage.on_template_evicted`

```python theme={null}
on_template_evicted(self, func: Callable[[TemplateEviction], Any]) -> Callable[[TemplateEviction], Any]
```

Register a handler called, synchronously and in this process, after the template store drops cached content.

Called on the process that wrote or deleted a template, on every bus member applying
the fleet's template eviction, and on a whole-cache clear. A handler that raises
propagates to the dropping call. A decorator: returns `func`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `func` | `Callable[[TemplateEviction], Any]` | — | — |

#### template\_reads

`tai42_contract.app.facets.execution.AppStorage.template_reads`

```python theme={null}
template_reads(self) -> AbstractContextManager[set[str]]
```

Record, into the yielded set, the id of every stored template a render inside the block resolves or probes.

A by-id render's whole locale fallback chain and every `{% include %}` /
`{% extends %}` / `{% import %}` target, at any depth. Blocks nest; each records.

## AppSubApp

`tai42_contract.app.facets.runtime.AppSubApp`

```python theme={null}
class AppSubApp(Protocol)
```

Access to the sub-app MCP router.

### Members

#### mcp\_sub\_app\_router

`tai42_contract.app.facets.runtime.AppSubApp.mcp_sub_app_router`

```python theme={null}
mcp_sub_app_router: SubMcpAppRouter
```

The router for mounted sub-app MCP servers.

## AppToolMeta

`tai42_contract.app.facets.authoring.AppToolMeta`

```python theme={null}
class AppToolMeta(Protocol)
```

The tool-metadata namespace (`app.tool_meta`) — the organizational overlay over any live tool.

The overlay is a folder tree plus a per-tool row (display name, folder
placement, tags, badges, a hidden override).
`store` is the `ToolMetaStore` view the routes
and the preset lifecycle cascade read and write. `patch` is the in-process edit
seam beside the HTTP PATCH door.

### Members

#### store

`tai42_contract.app.facets.authoring.AppToolMeta.store`

```python theme={null}
store: ToolMetaStore
```

The tool-metadata overlay store the routes and preset cascade read and write.

#### patch

`tai42_contract.app.facets.authoring.AppToolMeta.patch`

```python theme={null}
async patch(
    self,
    tool_name: str,
    *,
    tags: list[str] | None = None,
    folder_id: str | None = None,
) -> dict[str, Any]
```

Patch a tool's overlay row in-process and return its record.

The in-process sibling of the HTTP PATCH door, running the same operation so
validation is identical (an unknown `folder_id` is a loud error). Only the
arguments given are written: `folder_id` places the tool, and a `tags` list
REPLACES the whole tag set (array values are set replacements, not merges).
`tags=None` leaves the tag set untouched; `folder_id=None` leaves the
placement untouched.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `tool_name` | `str` | — | — |
| `tags` | `list[str] \| None` | `None` | — |
| `folder_id` | `str \| None` | `None` | — |

## AppTools

`tai42_contract.tools.AppTools`

```python theme={null}
class AppTools(Protocol)
```

Tool + toolkit registration / lookup surface.

### Members

#### tool\_title

`tai42_contract.tools.AppTools.tool_title`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
async get_tools(self) -> dict[str, Tool]
```

Return every assembled tool keyed by name.

#### get\_client\_tools

`tai42_contract.tools.AppTools.get_client_tools`

```python theme={null}
async get_client_tools(self, names: list[str] | None = None) -> list[ClientTool]
```

The tools named in `names` (all when `None`) as framework-neutral handles; an unknown name raises.

**Parameters**

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

#### run\_tool

`tai42_contract.tools.AppTools.run_tool`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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` | — | — |

#### pauses

`tai42_contract.tools.AppTools.pauses`

```python theme={null}
async pauses(self, key: str) -> bool
```

Whether a dispatch of `key` can return a park signal.

The tool registered under `key` declares `TOOL_META_PAUSES`, or it is an extension
branch whose base declares it or whose extension stack holds an extension registered
with `pauses=True`, or it is a preset (transformed tool) whose `parent_tool` chain
reaches such a tool. An unknown name answers `False` (its own dispatch surfaces the
not-found). A dispatch of a tool that answers `False` and returns a park signal is
refused with `UndeclaredPauseError`.

**Parameters**

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

#### remove\_tool

`tai42_contract.tools.AppTools.remove_tool`

```python theme={null}
remove_tool(self, name: str) -> None
```

Remove the tool registered under `name`.

**Parameters**

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

#### surface\_generation

`tai42_contract.tools.AppTools.surface_generation`

```python theme={null}
surface_generation(self) -> int
```

A number that changes whenever the set of tools this process lists changes.

Monotonic within a process; never compared across processes. A consumer that caches
anything derived from `get_tools`/`get_client_tools` keys the cache on it.

#### register\_tool\_info

`tai42_contract.tools.AppTools.register_tool_info`

```python theme={null}
register_tool_info(self, name: str, combos: Sequence[Sequence[ExtensionElement]] | None = None) -> None
```

Register base tool `name`'s extension combos, attaching each combo stack to the base.

**Parameters**

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

#### unregister\_tool\_info

`tai42_contract.tools.AppTools.unregister_tool_info`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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` | — | — |

## AppVersioning

`tai42_contract.app.facets.authoring.AppVersioning`

```python theme={null}
class AppVersioning(Protocol)
```

The generic versioned-document store namespace (`app.versioning`).

This is the platform persistence primitive — append-only versions + an active
pointer + rollback over an opaque JSONB body, discriminated by `kind`. Direct
consumers (e.g. AC policies under `kind="ac_policy"`) reach it here; presets
reach it through `AppPresets`, never as a new kind.

### Members

#### store

`tai42_contract.app.facets.authoring.AppVersioning.store`

```python theme={null}
store: VersionedStore
```

The append-only versioned-document store backing this namespace.

## AppWebhookVerifiers

`tai42_contract.app.facets.messaging.AppWebhookVerifiers`

```python theme={null}
class AppWebhookVerifiers(Protocol)
```

The webhook-verifier registry namespace (`app.webhook_verifiers`).

### Members

#### register

`tai42_contract.app.facets.messaging.AppWebhookVerifiers.register`

```python theme={null}
register(self, name: str, verifier: WebhookVerifier) -> None
```

Register a `WebhookVerifier` under `name`.

A provider plugin calls this through the `tai42_app` handle when its
import-only `webhook_verifier_modules` entry loads. Registering a name
already taken raises loudly — a silent overwrite could swap a topic's
verifier out from under a live binding.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `verifier` | `WebhookVerifier` | — | — |

#### get

`tai42_contract.app.facets.messaging.AppWebhookVerifiers.get`

```python theme={null}
get(self, name: str) -> WebhookVerifier
```

Fetch a registered verifier by name; raise loudly on an unknown name.

Resolution happens when a verifier is bound to a public webhook door, so
an unknown name surfaces at bind time as a loud failure, never a
silently-unverified door.

**Parameters**

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

## DeclaredRouteMetadata

`tai42_contract.app.facets.routing.DeclaredRouteMetadata`

```python theme={null}
class DeclaredRouteMetadata
```

The behavioral OpenAPI properties a route DECLARES.

A route registered through the operations adapter supplies this
from its operation's metadata + declared error classes; a native `/api/*`
handler passes it explicitly at its `custom_route` registration. Its
`reload_gated` / `reads_body` / error statuses / success status feed the
emitted spec and the coverage/parity gates.

`additional_success_statuses` names further 2xx codes one method may answer
besides `success_status`; each is emitted as its own success response.

**Attributes**

| Attribute | Type |
| - | - |
| `reload_gated` | `bool` |
| `reads_body` | `bool` |
| `error_statuses` | `tuple[int, ...]` |
| `success_status` | `int` |
| `additional_success_statuses` | `tuple[int, ...]` |
| `max_body_bytes` | `int \| None` |
| `rate_limit_family` | `str \| None` |
| `rate_limit_budget` | `RateLimitBudget \| None` |

## HostedUiPaths

`tai42_contract.app.facets.routing.HostedUiPaths`

```python theme={null}
class HostedUiPaths
```

The page addresses of the hosted UI, as the deployment declares them.

`login_path`, `oauth_callback_path` and `connectors_path` are same-origin paths; a
claim link carries its token in the login page's `#<claim_fragment_key>=` fragment and an
invite link in its `?<invite_query_key>=` query.

**Attributes**

| Attribute | Type |
| - | - |
| `login_path` | `str` |
| `claim_fragment_key` | `str` |
| `invite_query_key` | `str` |
| `oauth_callback_path` | `str` |
| `connectors_path` | `str` |

## PendingMessage

`tai42_contract.app.facets.messaging.PendingMessage`

```python theme={null}
class PendingMessage(BaseModel)
```

One participant message accepted on a thread but not yet carried into a turn.

The projection `AppConversations.pending_messages` returns, so a body running inside a
turn can learn a newer message is waiting and stop before an irreversible step. `message_id`
is the accepted record's id, `text` its verbatim inbound text, `accepted_at` the epoch
seconds it was accepted at (the thread index's own score). Frozen.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `message_id` | `str` |
| `text` | `str` |
| `accepted_at` | `float` |

## RateLimitBudget

`tai42_contract.app.facets.routing.RateLimitBudget`

```python theme={null}
class RateLimitBudget
```

A route family's default flood-control budget: requests per 60 s window and per 10 s burst window.

**Attributes**

| Attribute | Type |
| - | - |
| `limit` | `int` |
| `burst` | `int` |

## RouteAction

`tai42_contract.app.facets.routing.RouteAction`

```python theme={null}
RouteAction = Literal['read', 'write', 'fenced', 'secret']
```

## TaiApp

`tai42_contract.app.TaiApp`

```python theme={null}
class TaiApp(Protocol)
```

The assembled facade — per-feature sub-protocols exposed as namespaces.

### Members

#### tools

`tai42_contract.app.TaiApp.tools`

```python theme={null}
tools: AppTools
```

Tool and toolkit registration and lookup.

#### agents

`tai42_contract.app.TaiApp.agents`

```python theme={null}
agents: AppAgents
```

Agent registration and access.

#### backends

`tai42_contract.app.TaiApp.backends`

```python theme={null}
backends: AppBackends
```

Task backend registration and access.

#### sandboxes

`tai42_contract.app.TaiApp.sandboxes`

```python theme={null}
sandboxes: AppSandboxes
```

Sandbox-provider registration and access.

#### storage

`tai42_contract.app.TaiApp.storage`

```python theme={null}
storage: AppStorage
```

Storage-provider registration and access.

#### connectors

`tai42_contract.app.TaiApp.connectors`

```python theme={null}
connectors: AppConnectors
```

Connector-provider registration and credential resolution.

#### accounts

`tai42_contract.app.TaiApp.accounts`

```python theme={null}
accounts: AppAccounts
```

Read access to the current epoch's live identity/accounts providers.

#### webhook\_verifiers

`tai42_contract.app.TaiApp.webhook_verifiers`

```python theme={null}
webhook_verifiers: AppWebhookVerifiers
```

Inbound webhook verifier registration and lookup.

#### channels

`tai42_contract.app.TaiApp.channels`

```python theme={null}
channels: AppChannels
```

Channel registration and lookup.

#### conversations

`tai42_contract.app.TaiApp.conversations`

```python theme={null}
conversations: AppConversations
```

Inbound-message and delivery-status entry surface for medium adapters.

#### media

`tai42_contract.app.TaiApp.media`

```python theme={null}
media: AppMedia
```

Served-media ingestion entry surface for channel adapters and the upload door.

#### monitoring

`tai42_contract.app.TaiApp.monitoring`

```python theme={null}
monitoring: AppMonitoring
```

Monitoring backend registration and access.

#### extensions

`tai42_contract.app.TaiApp.extensions`

```python theme={null}
extensions: AppExtensions
```

Tool-extension factory registration and lookup.

#### interactions

`tai42_contract.app.TaiApp.interactions`

```python theme={null}
interactions: AppInteractions
```

The `ask` interactions facade.

#### http

`tai42_contract.app.TaiApp.http`

```python theme={null}
http: AppHttp
```

HTTP middleware, route registration, and mount introspection.

#### clients

`tai42_contract.app.TaiApp.clients`

```python theme={null}
clients: AppClients
```

Pooled async client lifecycle for the process.

#### lifecycle

`tai42_contract.app.TaiApp.lifecycle`

```python theme={null}
lifecycle: AppLifecycle
```

Startup, shutdown, reload, and post-swap lifecycle hook registration.

#### admin

`tai42_contract.app.TaiApp.admin`

```python theme={null}
admin: AppAdmin
```

In-process admin operations (binding, tool reload, config reload).

#### config

`tai42_contract.app.TaiApp.config`

```python theme={null}
config: AppConfig
```

Access to the process config manager.

#### backup

`tai42_contract.app.TaiApp.backup`

```python theme={null}
backup: AppBackup
```

Named backup-section registration and export/import.

#### sub\_app

`tai42_contract.app.TaiApp.sub_app`

```python theme={null}
sub_app: AppSubApp
```

Access to the sub-app router.

#### versioning

`tai42_contract.app.TaiApp.versioning`

```python theme={null}
versioning: AppVersioning
```

The generic versioned-document store.

#### presets

`tai42_contract.app.TaiApp.presets`

```python theme={null}
presets: AppPresets
```

The presets namespace (typed view plus bind kernel).

#### tool\_meta

`tai42_contract.app.TaiApp.tool_meta`

```python theme={null}
tool_meta: AppToolMeta
```

The tool-metadata overlay over any live tool.

#### states

`tai42_contract.app.TaiApp.states`

```python theme={null}
states: AppStates
```

The subject-keyed state store.

## tai42\_app

`tai42_contract.app.tai42_app`

```python theme={null}
tai42_app: _TaiAppRuntime = cast('_TaiAppRuntime', _tai_app_handle)
```


# Backends (tai42_contract.backend)
Source: https://docs.tai42.ai/reference/python-sdk/contract-backend

The Backend protocol a compute backend implements.

Execution-backend contract.

Exposes the `Backend` ABC, the `BackendRuntime` ABC one launch subcommand implements, the
`CallbackSchema`, and the scheduling protocol's names and models.

## CONSUMING\_RUNTIME

`tai42_contract.backend.runtime.CONSUMING_RUNTIME`

```python theme={null}
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.

## SCHEDULE\_BRANCH\_SUFFIX

`tai42_contract.backend.scheduling.SCHEDULE_BRANCH_SUFFIX`

```python theme={null}
SCHEDULE_BRANCH_SUFFIX: Final = '_schedule_task'
```

## SCHEDULE\_CADENCE\_KEY

`tai42_contract.backend.scheduling.SCHEDULE_CADENCE_KEY`

```python theme={null}
SCHEDULE_CADENCE_KEY: Final = 'backend_schedule'
```

## SCHEDULE\_DELETE\_TOOL

`tai42_contract.backend.scheduling.SCHEDULE_DELETE_TOOL`

```python theme={null}
SCHEDULE_DELETE_TOOL: Final = 'backend_delete_schedule'
```

## SCHEDULE\_EXPORT\_TOOL

`tai42_contract.backend.scheduling.SCHEDULE_EXPORT_TOOL`

```python theme={null}
SCHEDULE_EXPORT_TOOL: Final = 'backend_export_schedules'
```

## SCHEDULE\_EXTENSION

`tai42_contract.backend.scheduling.SCHEDULE_EXTENSION`

```python theme={null}
SCHEDULE_EXTENSION: Final = 'schedule_task'
```

## SCHEDULE\_IMPORT\_TOOL

`tai42_contract.backend.scheduling.SCHEDULE_IMPORT_TOOL`

```python theme={null}
SCHEDULE_IMPORT_TOOL: Final = 'backend_import_schedules'
```

## SCHEDULE\_LIST\_TOOL

`tai42_contract.backend.scheduling.SCHEDULE_LIST_TOOL`

```python theme={null}
SCHEDULE_LIST_TOOL: Final = 'backend_list_schedules'
```

## SCHEDULE\_MARKER\_TOOLS

`tai42_contract.backend.scheduling.SCHEDULE_MARKER_TOOLS`

```python theme={null}
SCHEDULE_MARKER_TOOLS: Final = (SCHEDULE_LIST_TOOL, SCHEDULE_DELETE_TOOL)
```

## SCHEDULE\_NAME\_KEY

`tai42_contract.backend.scheduling.SCHEDULE_NAME_KEY`

```python theme={null}
SCHEDULE_NAME_KEY: Final = 'backend_schedule_name'
```

## Backend

`tai42_contract.backend.base.Backend`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
name: str
```

The launch subcommand that selects this runtime.

#### mode

`tai42_contract.backend.runtime.BackendRuntime.mode`

```python theme={null}
mode: ExecutionMode
```

How the host must drive the run body.

#### consumes\_work

`tai42_contract.backend.runtime.BackendRuntime.consumes_work`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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 take new work; one still finishing the
job it holds exits after it, and is not waited for. 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`

```python theme={null}
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`

```python theme={null}
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={})})]` |

## CrontabCadence

`tai42_contract.backend.scheduling.CrontabCadence`

```python theme={null}
class CrontabCadence(BaseModel)
```

Fire on a five-field crontab (minute, hour, day of month, month, day of week).

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `kind` | `Literal['crontab']` |
| `minute` | `str` |
| `hour` | `str` |
| `day_of_month` | `str` |
| `month_of_year` | `str` |
| `day_of_week` | `str` |

## ExecutionMode

`tai42_contract.backend.runtime.ExecutionMode`

```python theme={null}
class ExecutionMode(StrEnum)
```

How a runtime's run body must be driven.

### Members

#### on\_loop

`tai42_contract.backend.runtime.ExecutionMode.on_loop`

```python theme={null}
on_loop = 'on_loop'
```

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

#### worker\_thread

`tai42_contract.backend.runtime.ExecutionMode.worker_thread`

```python theme={null}
worker_thread = 'worker_thread'
```

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

#### inline

`tai42_contract.backend.runtime.ExecutionMode.inline`

```python theme={null}
inline = 'inline'
```

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

## FleetOpApplied

`tai42_contract.backend.runtime.FleetOpApplied`

```python theme={null}
class FleetOpApplied(BaseModel)
```

A worker-bus op that applied in this process, as a post-apply handler receives it.

`effects` is what the op changed here (empty for a query or a process exit); a handler
decides on it, never on `op`, which names the op for logs and a turnover reason.
`budget` is the seconds left before the publisher's report cut, measured from this
process's receipt of the op; a post-apply obligation that cannot finish within it must raise.

**Attributes**

| Attribute | Type |
| - | - |
| `op` | `str` |
| `effects` | `frozenset[FleetOpEffect]` |
| `budget` | `float` |

## FleetOpEffect

`tai42_contract.backend.runtime.FleetOpEffect`

```python theme={null}
class FleetOpEffect(StrEnum)
```

What applying a worker-bus op changed in this process — the vocabulary a post-apply handler decides on.

### Members

#### registry

`tai42_contract.backend.runtime.FleetOpEffect.registry`

```python theme={null}
registry = 'registry'
```

This process's tool registry changed.

#### templates

`tai42_contract.backend.runtime.FleetOpEffect.templates`

```python theme={null}
templates = 'templates'
```

This process's compiled-template cache was dropped.

## IntervalCadence

`tai42_contract.backend.scheduling.IntervalCadence`

```python theme={null}
class IntervalCadence(BaseModel)
```

Fire every `every` seconds; `relative` aligns the schedule to the interval's own clock.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `kind` | `Literal['interval']` |
| `every` | `float` |
| `relative` | `bool` |

## ScheduleCadence

`tai42_contract.backend.scheduling.ScheduleCadence`

```python theme={null}
ScheduleCadence = Annotated[IntervalCadence | CrontabCadence, Field(discriminator='kind')]
```

## ScheduleCreate

`tai42_contract.backend.scheduling.ScheduleCreate`

```python theme={null}
class ScheduleCreate(ParkableDoorMixin)
```

Create a schedule that runs `tool_name` on `cadence`, or once now when no cadence is given.

`tool_kwargs` are the arguments each fire passes to the tool, the tool's alone and forwarded
untouched — a tool whose OWN argument is named `subject` carries it here like any argument.
`subject` is the OPTIONAL top-level door field naming the `schedule`-door state context each
fire re-establishes: the create door stamps it onto the job, and the fire keys its state writes and
parks on it (it never reaches the base tool). `state_binding` is the OPTIONAL door-layer binding
the fire applies around the started tool alone (never the base tool's). `schedule_name` names a
recurring schedule; without it the door derives one from the tool, its arguments and the cadence.

A schedule is a parkable-driving door: it carries the four `ParkableDoorMixin` jqs
(`start_expr` builds the fired tool's kwargs; `cancel_expr` / `resume_expr` act on the run's
parked interactions; `extras_expr` builds the started run's extras), each evaluated over the
fired tool's arguments with the run's parked interactions bound as `$parked`. Any contract jq
needs an `execution_key` (the api-key `user_id` the recurring fire runs as, so a park it
raises can be rebound and resumed under that authority).

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `tool_name` | `str` |
| `tool_kwargs` | `dict[str, Any]` |
| `cadence` | `ScheduleCadence \| None` |
| `schedule_name` | `str \| None` |
| `execution_key` | `str \| None` |
| `subject` | `StateSubject \| None` |
| `state_binding` | `StateBinding \| None` |

## ScheduleImportError

`tai42_contract.backend.scheduling.ScheduleImportError`

```python theme={null}
class ScheduleImportError(BaseModel)
```

One import row the backend refused, at its `index` in the rows it was handed.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `index` | `int` |
| `name` | `str \| None` |
| `error` | `str` |

## ScheduleImportMode

`tai42_contract.backend.scheduling.ScheduleImportMode`

```python theme={null}
ScheduleImportMode = Literal['skip', 'overwrite']
```

## ScheduleImportReport

`tai42_contract.backend.scheduling.ScheduleImportReport`

```python theme={null}
class ScheduleImportReport(BaseModel)
```

What a schedule import did: counts per outcome and the refused rows.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `created` | `int` |
| `updated` | `int` |
| `skipped` | `int` |
| `skipped_existing` | `int` |
| `errors` | `list[ScheduleImportError]` |

## ScheduleListRow

`tai42_contract.backend.scheduling.ScheduleListRow`

```python theme={null}
class ScheduleListRow(BaseModel)
```

One row of the schedule listing: no arguments, no kwargs.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `name` | `str` |
| `tool` | `str` |
| `cadence` | `ScheduleCadence` |
| `enabled` | `bool` |
| `next_run_at_ts` | `float \| None` |
| `next_run_at_iso` | `str \| None` |
| `error` | `ScheduleRowError \| None` |

## ScheduleRecord

`tai42_contract.backend.scheduling.ScheduleRecord`

```python theme={null}
class ScheduleRecord(BaseModel)
```

One exported or imported schedule: the durable definition, never runtime state.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `name` | `str` |
| `tool` | `str` |
| `args` | `list[Any]` |
| `kwargs` | `dict[str, Any]` |
| `cadence` | `ScheduleCadence` |
| `enabled` | `bool` |

## ScheduleRowError

`tai42_contract.backend.scheduling.ScheduleRowError`

```python theme={null}
class ScheduleRowError(BaseModel)
```

A backend's last scheduling failure for a schedule, when the backend records one.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `message` | `str` |
| `at_iso` | `str \| None` |


# Channels (tai42_contract.channels)
Source: https://docs.tai42.ai/reference/python-sdk/contract-channels

The Channel protocol a delivery channel plugin implements.

Channel delivery contracts.

A `Channel` pushes an `ask` question to a human on a specific
medium (Telegram, Slack, SMS, ...) and bridges the human's reply back into the
interactions store by forwarding it to the delivery's public `callback_url`.
Channels are registered on the app handle (`tai42_app.channels`) by channel
plugins and looked up by name when `ask` is called with `channel=...`.
Delivery either returns a `SendOutcome` (success) or raises
`ChannelDeliveryError` (any failure) — never a bool.

A channel also sends fire-and-forget notifications: `notify` pushes one
`ChannelNotification` to a human with no interaction, no ticket, and no
reply path, under the same loud-failure rule; it returns a `SendOutcome`
naming the identity and address it sent from and to and the per-message ids the
medium assigned the send (empty when the medium exposes none), never a bool.
Before either send, `resolve_address` gives the `ChannelAddress` the
channel would send to, or raises `ChannelAddressError`.

When the platform takes a delivered question down by a path that is not the channel's own
forwarded reply, it hands the channel a `ChannelWithdrawal` through the channel's
optional `withdraw` member, so the channel releases what it kept for that question.

A channel whose medium limits free-form replies to a window after the client's last message
reports that window as a `ReplyWindow` through its optional `reply_window` member.

## NOTIFICATION\_FOOTER\_MAX\_CHARS

`tai42_contract.channels.options.NOTIFICATION_FOOTER_MAX_CHARS`

```python theme={null}
NOTIFICATION_FOOTER_MAX_CHARS = MEDIA_CAPTION_MAX_CHARS
```

## NOTIFICATION\_SECTIONS\_MAX

`tai42_contract.channels.options.NOTIFICATION_SECTIONS_MAX`

```python theme={null}
NOTIFICATION_SECTIONS_MAX = 10
```

## OPTION\_ID\_MAX\_CHARS

`tai42_contract.channels.options.OPTION_ID_MAX_CHARS`

```python theme={null}
OPTION_ID_MAX_CHARS = 256
```

## AnswerForwardError

`tai42_contract.channels.errors.AnswerForwardError`

```python theme={null}
class AnswerForwardError(Exception)
```

The interactions answer door rejected a forwarded answer on a status the shared ladder cannot resolve.

The unresolvable statuses are 401/413/5xx or a transport fault. Raised by
`AppChannels.handle_inbound_answer` WITHOUT releasing the
correlation, so the channel's transport-level retry (the provider's webhook
redelivery) re-runs the ladder and the answer is never silently lost. A channel
lets it propagate out of its inbound webhook so the provider redelivers.

## Channel

`tai42_contract.channels.protocol.Channel`

```python theme={null}
class Channel(Protocol)
```

Delivers one question to a human on a specific medium.

A channel plugin registers an instance under a name
(`tai42_app.channels.register`); `ask` resolves it by name and calls
`deliver` after the interaction is persisted and its callback ticket is
minted. A channel never reaches the interactions store directly: the
human's reply travels back through the delivery's public `callback_url`.

A channel MAY advertise richer support with seven OPTIONAL, class-level
capability flags — `supports_media_notifications`,
`supports_template_notifications`, `supports_interactive_notifications`,
`supports_location_notifications`, `supports_form_notifications` (all
five for `notify`), `supports_form_delivery` and
`supports_form_reaction` (both for `deliver`) — set
as plain class
attributes. They are a documented convention, NOT Protocol members: a
channel that supports the richer form sets the matching attribute to
`True`; a channel that omits it advertises no support (absent =
`False`). Because they are not part of the Protocol, a text-only channel
that declares none is still a valid `Channel` (both structurally and under
runtime `isinstance`). The ask/notify helpers read them defensively with
`getattr(channel, "<flag>", False)` and refuse the matching richer send to
a channel that does not advertise the flag: `notify_user` refuses a media,
template, options, sections, location or schema notification, and the
`ask` helper
refuses a `form` delivery, to a channel without the flag — so a channel
that reads only the plain fields can never silently drop the extra content.
A channel that does not advertise `supports_form_delivery` never receives
a `form` delivery, and one that does not advertise
`supports_form_notifications` never receives a `schema` notification. A
channel that advertises `supports_form_notifications` MUST, when a form
notification carries a `form_tag`, carry that opaque per-send tag with the
form on its own medium (never into the published form artefact) and hand it
back on the participant's submission as `accept(form_tag=...)` — the tag
rides the form's gate, so it needs no capability flag of its own.
`supports_form_reaction` is the delivery-side flag for a REACTING form (one
whose ask names a `reaction_tool` and carries `reactions` triggers): the
`ask` helper, having already confirmed `supports_form_delivery`, refuses a
reacting form to a channel that does not ALSO advertise
`supports_form_reaction` — so a form that reacts while open is never
delivered to a medium that cannot route its triggers back (it is refused
loudly at the ask door, never silently rendered inert). A non-reacting form
needs only `supports_form_delivery`.

A form channel MAY also declare one OPTIONAL method, `validate_form_schema`,
following the same convention as the capability flags — a documented member,
NOT a Protocol method, so declaring it never tightens the runtime structural
check. `ask` reads it defensively with
`getattr(channel, "validate_form_schema", None)` right after the generic
channel-deliverable subset check and, when present, calls
`channel.validate_form_schema(schema, question)` at ask-time, BEFORE any
state is written. It enforces the channel's OWN ask-time-knowable form limits
(reserved property names, per-medium Block Kit / Flow caps, question-text caps)
over the schema AND the question text — limits the generic subset does not
know — raising `ValueError` naming the offending property/limit on a
violation, so a question or schema the channel could never render is refused up
front instead of persisting a question that only fails at delivery. A channel
that omits it advertises no extra ask-time limits; its delivery path still
refuses an unrenderable question or schema (a permanent
`ChannelInputError`). The SAME hook is reused for a form notification:
the notify helper calls `channel.validate_form_schema(schema, message)` with
the notification's `message` as the `question` argument before the send, so
one declared method covers both the ask and the notify form surfaces. A
conversation's send admission runs the same hook once per form part, with the
part's final message as the `question`, before any part of the reply is sent.

A channel that advertises `supports_template_notifications` MAY also declare one OPTIONAL
method, `validate_template`, following the same documented-member convention (read
defensively with `getattr(channel, "validate_template", None)`, NOT a Protocol method, so
declaring it never tightens the runtime structural check). The send helpers call
`channel.validate_template(template)` right after the capability gate, BEFORE the send: it
parses the template's OPAQUE `parameters` against the channel's OWN template-parameter schema
and raises `ValueError` on a shape the channel could never map — so a template the channel
could never render is refused up front instead of failing at delivery. A channel that omits the
hook advertises no ask-time parameter check; its `notify` still refuses an unmappable template
at send time (a permanent `ChannelInputError`). A conversation's send admission runs the
same hook once per template part, before any part of the reply is sent. The platform never
looks inside `parameters` itself; the declaring channel owns the shape end to end.

A channel MAY also declare the OPTIONAL outbound message-length cap it splits a long answer
against — an OPTIONAL `ClassVar max_message_chars: int` giving the medium's own per-message
character limit, read defensively with `getattr(channel, "max_message_chars", None)` (the
same documented-member convention, NOT a Protocol member). The conversation-delivery machine
resolves a routed channel's split width as the operator override
(`CONVERSATIONS_MAX_MESSAGE_CHARS`) when set, else this declared cap; a channel that declares
neither (and has no override) is a loud config error at send, never a silent unbounded or
truncated send.

A channel MAY also declare the OPTIONAL "working-on-it" (typing) signal — the
same documented-member convention as `validate_form_schema`
and the capability flags, NOT Protocol members (so declaring them never tightens
the runtime structural check and a channel that omits them stays a valid
`Channel`). It is two members. An OPTIONAL `ClassVar
working_signal_expiry_seconds: float | None` gives the vendor indicator's lifetime
in seconds; `None` (or absent) means the channel emits no working signal and the
caller's refresh loop never starts, read defensively with `getattr(channel,
"working_signal_expiry_seconds", None)`. An OPTIONAL method `async def
signal_working(self, *, recipient: str, sender_identity: str | None = None,
provider_message_id: str | None = None, active: bool = True) -> None` asserts
(`active=True`) or clears (`active=False`) the working-on-it indicator to
`recipient` (the participant address, as `notify` addresses one), optionally
from `sender_identity` (`None` = channel default), referencing the inbound
`provider_message_id` where the medium's API ties the indicator to a specific
inbound message. A channel whose indicator self-expires implements only the assert
and treats `active=False` as a no-op; a channel that emits explicit frames sends a
start frame on `True` and a stop frame on `False`. It is fire-and-forget,
carries no reply, and raises `ChannelDeliveryError` ONLY on a genuine send
failure the caller logs, never for a transient it can ignore.

A channel that keeps something per delivered question MAY also declare one OPTIONAL
method, `async def withdraw(self, withdrawal: ChannelWithdrawal) -> None` — the same
documented-member convention, NOT a Protocol method, read defensively with
`getattr(channel, "withdraw", None)`. The platform calls it when it takes a delivered
question down by a path that is not the channel's own forwarded reply (a cancel, an erase
of the question's thread, route or person, an expiry). The channel releases EVERYTHING it
reserved or cached for `withdrawal.interaction_id` at delivery — the per-address pending
correlation and any per-interaction sidecar — resolving the address from
`withdrawal.recipient` exactly as its `deliver` resolved `delivery.recipient`. It
MUST compare the stored interaction id and never drop a hold another ask now has on the
same address. It MUST be idempotent and a no-op when nothing is held (expired, already
forwarded, never reserved — a link-answered format reserves nothing). It touches no
message on the medium: the question already sent stays where it is, and a late reply to
it takes the inbound answer ladder's no-longer-pending path. It raises
`ChannelDeliveryError` (`retryable=True` for a transient store fault) only on a
fault, never for "nothing to release". A channel that keeps nothing withdrawable omits the
member (absent = nothing to release).

A channel whose medium allows a free-form reply only within a window after the client's
last message MAY also declare one OPTIONAL method, `async def reply_window(self, *,
recipient: str, sender_identity: str | None = None) -> ReplyWindow` — the same
documented-member convention, NOT a Protocol method, read defensively with
`getattr(channel, "reply_window", None)`. It reports the window for `recipient` (the
client address, as `deliver` addresses one) and `sender_identity` (our identity on the
medium; `None` = the channel default, resolved exactly as `deliver` resolves it): a
`ReplyWindow` that is `open` with its `closes_at`, `closed`, or `none` for a
pair the medium keeps no window for. It reads state only and sends nothing. It raises on a
fault (an unreachable store, a corrupt stored value, an unaddressable pair), never answers a
guessed state. A channel that omits the member has no reply window: the platform reports
`none`. The medium's own rejection of a send outside its window stays the final check.

### Members

#### resolve\_address

`tai42_contract.channels.protocol.Channel.resolve_address`

```python theme={null}
resolve_address(self, recipient: str | None, sender_identity: str | None) -> ChannelAddress
```

The identity and participant address this channel would send to, known before sending.

Synchronous, no I/O. `recipient` and `sender_identity` are the send's own values
(`None` = the channel's default), resolved exactly as `notify` / `deliver` resolve
them. The identity is the one the send goes from, and a completed send's
`SendOutcome` reports the same identity. The address may not be the canonical
one: a medium that resolves a handle only when it sends returns the handle here. The
platform uses this address only to place a send that never reported an outcome (it
raised, it timed out, it was cancelled, or the process stopped); a completed send is
placed by its `SendOutcome`. Raises `ChannelAddressError` when the target
cannot be resolved (a recipient off the operator allowlist, no recipient and no
configured default).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `recipient` | `str \| None` | — | — |
| `sender_identity` | `str \| None` | — | — |

#### deliver

`tai42_contract.channels.protocol.Channel.deliver`

```python theme={null}
async deliver(self, delivery: ChannelDelivery) -> SendOutcome
```

Push `delivery` to the medium, or raise `ChannelDeliveryError`.

Send the question to the resolved recipient — `delivery.recipient`
when set (after checking it against the plugin's operator allowlist),
else the plugin's operator-configured default — and arrange for
the reply to reach `delivery.callback_url` — either a tappable link
carrying the URL, or an inbound-route correlation the plugin stores.
Any delivery failure — an unreachable or rejecting medium, a recipient
outside the operator allowlist, a required credential or recipient not
configured, a bad send response — raises
`ChannelDeliveryError`; a return is the only success signal and
yields the `SendOutcome` of the question's messages (the identity
and participant address it went from and to, and the per-message ids the
medium assigned, empty when it exposes none). One send attempt only:
retrying is the caller's decision, never
an implicit loop here — the raised error's `retryable` and
`retry_after` drive that decision, so a fault the medium can recover
from is classified rather than blind-retried here. The dispatcher never
hands a delivery whose `timeout_at` has passed.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `delivery` | `ChannelDelivery` | — | — |

#### notify

`tai42_contract.channels.protocol.Channel.notify`

```python theme={null}
async notify(self, notification: ChannelNotification) -> SendOutcome
```

Send a fire-and-forget message, or raise `ChannelDeliveryError`.

No interaction, no ticket, no callback, no reply. Any delivery failure raises
`ChannelDeliveryError`; a permanent refusal of the input's shape or
content (an input the medium cannot render BY NATURE) raises
`ChannelInputError` instead — retrying it cannot succeed. A return means
the medium ACCEPTED the message —
not that a human saw it — and yields the `SendOutcome`: the identity and
participant address the message went from and to, and the per-message ids the
medium assigned this send (several when the medium splits a long message, empty
when it exposes no id), which later correlate an out-of-band delivery receipt or a
quote back to this send. One send attempt only, no retry. A channel that cannot
notify raises `NotImplementedError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `notification` | `ChannelNotification` | — | — |

## ChannelAddress

`tai42_contract.channels.delivery.ChannelAddress`

```python theme={null}
class ChannelAddress(BaseModel)
```

The identity and participant address a channel would send to, known before sending.

`our_identity` is the identity the send goes from; a completed send's
`SendOutcome` reports the same identity. `address` may not be the canonical
one: a medium that resolves a handle only when it sends gives the handle here.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `our_identity` | `str` |
| `address` | `str` |

## ChannelAddressError

`tai42_contract.channels.errors.ChannelAddressError`

```python theme={null}
class ChannelAddressError(ChannelDeliveryError)
```

Raised by `Channel.resolve_address` when the send's target cannot be resolved.

A caller-supplied recipient off the channel's operator allowlist, or no recipient and no
configured default: the send is refused before anything is recorded or sent. It is a
`ChannelDeliveryError` that is never retryable, so every caller that handles a
refused send handles this one the same way.

## ChannelDelivery

`tai42_contract.channels.delivery.ChannelDelivery`

```python theme={null}
class ChannelDelivery(BaseModel)
```

One question handed to a channel for out-of-band delivery.

`callback_url` is the public `/api/interactions/callback/{ticket}`
answer sink; the channel arranges for the human's reply to reach it.
`recipient` is the OPTIONAL caller-requested address (chat id, phone
number, ...): the channel plugin validates it against its operator-set
allowlist and refuses to send to an unlisted address; when omitted the
plugin sends to its operator-configured default recipient. It is an
address only, never a secret or credential.

`media` is OPTIONAL display media the channel renders alongside the
question (reusing `MediaItem`, the same shape and list-level caps the
ask REQUEST carries); a present list is non-empty. It is a pure enhancement,
NOT structure: a channel that renders only text simply ignores it and shows
the question, so it rides no capability flag and is never refused for a
channel that cannot render it. `options` is REQUIRED for `select` (the
answer set) and OPTIONAL for `text` as SUGGESTED REPLIES — a tapped option
submits its own text as the free-text answer; every other format carries none.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `interaction_id` | `str` |
| `recipient` | `str \| None` |
| `question` | `str` |
| `answer_format` | `str` |
| `schema` | `dict[str, Any] \| None` |
| `options` | `list[str] \| None` |
| `data` | `FormData \| None` |
| `pages` | `list[FormPage] \| None` |
| `reactions` | `FormReactions \| None` |
| `wording` | `Wording \| None` |
| `media` | `list[MediaItem] \| None` |
| `on_mismatch` | `AnswerMismatchPolicy` |
| `callback_url` | `str` |
| `timeout_at` | `datetime` |
| `sensitive` | `bool` |

## ChannelDeliveryError

`tai42_contract.channels.errors.ChannelDeliveryError`

```python theme={null}
class ChannelDeliveryError(Exception)
```

Raised by a `Channel` when delivering a question fails.

Every failure mode — an unreachable medium API, a rejected send, a missing
credential, a misconfigured recipient — raises this single typed error.
`deliver` NEVER returns a bool and NEVER silently drops a message: an
undeliverable question is a loud failure, so the only success signal is a
plain return.

`retryable` classifies the failure for the caller's retry decision: True
means transient (a medium 5xx, a rate limit, a transport fault or timeout)
and a fresh attempt may land. It defaults to False — a rejected recipient, a
bad credential, and any unrecognised fault fail on the first try rather than
being blind-retried. `retry_after` is the seconds the medium asked the
caller to wait (an HTTP `Retry-After`, say); meaningful only when
`retryable` is True.

**Attributes**

| Attribute | Type |
| - | - |
| `retryable` | — |
| `retry_after` | — |

## ChannelInputError

`tai42_contract.channels.errors.ChannelInputError`

```python theme={null}
class ChannelInputError(Exception)
```

A permanent refusal of the input's shape or content by the channel.

The input is contract-valid but the medium cannot render it BY NATURE — e.g. a
`data:` image URL to a channel that sends only public `https` sources.
Retrying the same input can never succeed, so this is distinct from
`ChannelDeliveryError` (a delivery failure the caller may retry): the
operation door maps it to the client-error (400) class, never the retryable
503 a transient delivery failure earns.

## ChannelNotification

`tai42_contract.channels.notification.ChannelNotification`

```python theme={null}
class ChannelNotification(BaseModel)
```

One fire-and-forget message handed to a channel.

A notification carries no interaction, no ticket, no `callback_url` and
no deadline: the channel sends the message and nothing travels back.
`recipient` is the OPTIONAL caller-requested address (chat id, phone
number, ...): the channel plugin validates it against its operator-set
allowlist and refuses to send to an unlisted address; when omitted the
plugin sends to its operator-configured default recipient. It is an
address only, never a secret or credential.

`sender_identity` is the OPTIONAL address to send FROM when the channel fronts
several operator identities: an internal routing control set by the sending side,
never caller-supplied, and an address only — never a secret.

`message` is the human-readable text, non-blank BY DEFAULT — EXCEPT it may be the empty
string `""` for a CONTENT-ONLY send: a caption-less bubble that is just `media` or a
`location`, with no text carrier. The admissible states are "`message` non-blank" OR
"blank `message` WITH non-empty `media` OR a `location`"; a blank `message` with no
such content has nothing to deliver and is refused. (`message` stays REQUIRED — a
content-only sender passes `""` explicitly — because every caller constructs it in code
with the text in hand.) An interactive surface (`options`, `sections` or `schema`)
REQUIRES a non-blank `message` — a choice or a form needs a prompt — so a content-only
send carries none; a `template` likewise rides a non-blank `message`.

The OPTIONAL richer-send forms reuse the same `message` as the human-readable
equivalent. `media` is display media the channel sends alongside the message (reusing
`MediaItem`, image/document/video/audio/link); a present list is non-empty.
`location` is a shared geographic point (`LocationElement`). `template` sends a
pre-approved `ChannelTemplate` for out-of-window delivery. `options` is a flat
list of tappable `Option` entries — a `ReplyOption` (a tap submits its text
as a visitor message) or a `LinkOption` (a tap opens its url) — at most
`NOTIFICATION_OPTIONS_MAX`. `sections` is the sectioned alternative: titled
`OptionSection` groups of reply rows (rows summed across sections stay within
`NOTIFICATION_OPTIONS_MAX`). `header` is a single display-media header and `footer` a
short trailing line, each composing an interactive message (they REQUIRE `options` or
`sections`).

The composition rules (`check_interactive_composition`): `options` XOR
`sections` (one choice surface); `schema` excludes both (one interactive surface); a
`template` is the standalone out-of-window send, MUTUALLY EXCLUSIVE with every other
content and interactive field; `options`/`sections` and `schema` MAY each combine
with `media` and `location`. A channel that does not advertise the matching capability
flag (`supports_media_notifications` / `supports_location_notifications` /
`supports_template_notifications` / `supports_interactive_notifications` /
`supports_form_notifications`, the OPTIONAL class-attribute convention documented on
`Channel`) never receives the matching field.

`schema` is the form answer schema for an ASK-LESS FORM: the channel renders
`message` as the form's prompt and `schema` as the fillable form, and the
participant's submission enters the conversation as a participant message — no interaction,
no ticket, no callback, the same inbound path a tapped option takes. A present
`schema` is a non-empty dict; its deep shape is the sender's shared
channel-deliverable subset walk (the same split `ChannelDelivery` keeps),
never re-checked here. `schema` REQUIRES a non-blank `message` — a form needs
a prompt — and is MUTUALLY EXCLUSIVE with `template` and with `options` (one
message carries ONE interactive surface); it MAY combine with `media`. It rides
the `supports_form_notifications` capability flag, and a form channel's OPTIONAL
`validate_form_schema(schema, question)` hook (see `Channel`) is reused
at notify time with this `message` as the `question` argument, so the
channel's own form limits refuse an unrenderable form before the send. A conversation
part's delivery notification is held to the same hook before its reply's first chunk,
with this `message` as the `question`. Some channels
also constrain WHEN a form may be sent: WhatsApp delivers a notify-form only inside
the provider's customer-service window, and an out-of-window send fails loudly at the
channel — never silently downgraded.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `message` | `str` |
| `recipient` | `str \| None` |
| `sender_identity` | `str \| None` |
| `media` | `list[MediaItem] \| None` |
| `location` | `LocationElement \| None` |
| `template` | `ChannelTemplate \| None` |
| `options` | `list[Option] \| None` |
| `sections` | `list[OptionSection] \| None` |
| `header` | `MediaItem \| None` |
| `footer` | `str \| None` |
| `schema` | `dict[str, Any] \| None` |
| `data` | `FormData \| None` |
| `pages` | `list[FormPage] \| None` |
| `form_tag` | `str \| None` |
| `wording` | `Wording \| None` |

## ChannelTemplate

`tai42_contract.channels.templates.ChannelTemplate`

```python theme={null}
class ChannelTemplate(BaseModel)
```

A pre-approved, named template a channel sends outside its freeform window.

Some media only accept arbitrary text inside a bounded conversation window (a provider's
customer-service window); outside it, the sole accepted send is an operator-authored,
pre-approved template referenced by `name` in an approved `language` locale — both
required and non-blank.

`parameters` is the template's runtime arguments as an OPAQUE object: the platform
threads it UNOPENED (never looking inside it), and the channel that declares the
`supports_template_notifications` capability owns its shape — it validates `parameters`
against its OWN template-parameter schema through its OPTIONAL `validate_template` hook
(see `Channel`) and maps it to its own send API in its own
code. A template with no runtime arguments carries no `parameters`; a present
`parameters` is a non-empty dict.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `name` | `str` |
| `language` | `str` |
| `parameters` | `dict[str, Any] \| None` |

## ChannelWithdrawal

`tai42_contract.channels.withdrawal.ChannelWithdrawal`

```python theme={null}
class ChannelWithdrawal(BaseModel)
```

One delivered question the platform has taken down: release what the channel kept for it.

`interaction_id` and `recipient` are the two facts the channel reserved under at
delivery: the id of the question and the address the `ChannelDelivery` carried
(`None` when the delivery named none, so the channel resolves its own default exactly
as its `deliver` did).

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `interaction_id` | `str` |
| `recipient` | `str \| None` |

## Correlation

`tai42_contract.channels.correlation.Correlation`

```python theme={null}
class Correlation(BaseModel)
```

The per-address record a channel keeps while ONE parked ask awaits a reply.

When `ask` is delivered on a medium whose reply arrives as a fresh
inbound message (not a tap on a signed link), the channel stores this record
against a channel-computed correlation key and, when the participant's next reply
lands on that key, forwards it to `callback_url` (the delivery's public
answer sink). `interaction_id` identifies the parked ask (carried into
operator alerts, never re-derived); `ttl_deadline` is the tz-aware instant
past which the pending ask is stale and the key may be reclaimed. One pending
ask per address: a channel reserves the key before delivering and drops it
once the reply is forwarded, withdrawn or expired.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `callback_url` | `str` |
| `interaction_id` | `str` |
| `ttl_deadline` | `datetime` |
| `on_mismatch` | `AnswerMismatchPolicy` |
| `wording` | `Wording \| None` |

## CorrelationStore

`tai42_contract.channels.correlation.CorrelationStore`

```python theme={null}
class CorrelationStore(Protocol)
```

Storage primitives ONLY for the one-pending-per-address correlation record — no policy.

A channel that delivers `ask` questions whose replies arrive as fresh
inbound messages keeps a `Correlation` per waiting address so the
participant's next reply resolves the right parked ask. This port is the minimal
set/get/release surface over that store; the LADDER that interprets a
forwarded answer's outcome (forward, retry-in-place, bridge) lives in core and
reads this port — it is not the store's concern.

`key` is an OPAQUE channel-computed correlation key: it absorbs the divergent
per-channel shapes — a Twilio number pair, a Slack `thread_ts`, a Telegram
ForceReply `message_id`, a WhatsApp address — collapsing them to one string
the store never interprets. A channel with no correlated replies (a link-tap
or an external-answer medium) simply does not provide a store.

This is a STANDALONE optional port, NOT an extension of `Channel`: a
channel implements it separately (or not at all), and the core handler is
handed one explicitly rather than reaching it off the channel instance.

### Members

#### set\_correlation

`tai42_contract.channels.correlation.CorrelationStore.set_correlation`

```python theme={null}
async set_correlation(self, key: str, entry: Correlation, *, ttl_seconds: int) -> bool
```

Reserve `key` for `entry` with a `ttl_seconds` expiry, NX.

Returns True when the key was free and is now held; False when the key is
already held — the one-pending-per-address guarantee, so a second parked
ask for the same address never silently overwrites the first. `ttl_seconds`
bounds how long the reservation survives without a reply.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `key` | `str` | — | — |
| `entry` | `Correlation` | — | — |
| `ttl_seconds` | `int` | — | — |

#### get\_correlation

`tai42_contract.channels.correlation.CorrelationStore.get_correlation`

```python theme={null}
async get_correlation(self, key: str) -> Correlation | None
```

Return the record held under `key`, or `None` when none is held.

A non-destructive peek: it neither drops nor refreshes the reservation, so
the handler can inspect the pending ask and decide the outcome before
releasing.

**Parameters**

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

#### release\_correlation

`tai42_contract.channels.correlation.CorrelationStore.release_correlation`

```python theme={null}
async release_correlation(self, key: str) -> None
```

Drop any reservation held under `key`, idempotently.

A no-op when the key is already free (expired, forwarded, or never held),
so releasing twice — or racing an expiry — is never an error.

**Parameters**

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

## InboundAnswerOutcome

`tai42_contract.channels.inbound.InboundAnswerOutcome`

```python theme={null}
class InboundAnswerOutcome(StrEnum)
```

What the shared inbound-answer ladder decided for one inbound reply on a correlation key.

A channel maps this to its own transport ack.

**Attributes**

| Attribute | Type |
| - | - |
| `NO_CORRELATION` | — |
| `FORWARDED` | — |
| `RETRY_KEPT` | — |
| `BRIDGED` | — |
| `BRIDGED_KEPT` | — |

## InboundAnswerResult

`tai42_contract.channels.inbound.InboundAnswerResult`

```python theme={null}
class InboundAnswerResult(BaseModel)
```

The result of one inbound-answer ladder run.

`outcome` is the ladder's decision. `retry_reason` and `retry_field` carry the
door's OWN (already length-bounded) rejection message and the failing field name so a
channel that OWNS its correction surface (a re-opened WhatsApp Flow, a Slack modal's
inline Block-Kit error) can render the door's SPECIFIC message rather than a generic
line. Both are populated when the door rejected the answer's content — on
`InboundAnswerOutcome.RETRY_KEPT` (either `notice_owner` variant) and on a
hard-mismatch `InboundAnswerOutcome.BRIDGED` — and are `None` on every other
outcome (no correlation, a clean forward, a gone-ask 404 bridge). A channel that
renders no correction of its own simply ignores them and maps `outcome`.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `outcome` | `InboundAnswerOutcome` |
| `retry_reason` | `str \| None` |
| `retry_field` | `str \| None` |

## InboundBridge

`tai42_contract.channels.inbound.InboundBridge`

```python theme={null}
class InboundBridge(BaseModel)
```

The context a bridged turn needs when a reply is not (or no longer) an answer.

A channel hands one of these to `AppChannels.handle_inbound_answer` alongside
the correlation key and answer value. `channel_id` is the registered channel
name; `our_identity` and `client_address` are the conversation's two addresses
(the operator identity the turn answers from, and the participant's attested address /
thread); `cap_key` is the party the per-address turn cap holds accountable;
`provider_message_id` dedupes a provider redelivery at the conversation seam;
`medium_message_id` is the id the medium gives the message itself, the one a later
quote names (`None` only when the medium has no such id);
`reply_to_medium_message_id` is the medium's id of the message this reply quotes (`None`
when it quotes none); both arms carry it, so the asker or the bridged turn reads the quote;
`bridge_text` is the channel's faithful rendering of the participant's message for a
bridged turn.

`owns_retry_notice` lets a channel OWN the participant-facing correction message on a
retryable rejection. The default (False) is that the ladder sends the generic
"that didn't match, try again" notice on `InboundAnswerOutcome.RETRY_KEPT`.
When True, the channel's correction surface IS a re-ask the channel renders off
RETRY\_KEPT (a re-opened WhatsApp Flow, a Slack modal's inline Block-Kit error), so
the ladder SKIPS its notice to avoid double-messaging — it still keeps the
correlation and still emits the operator event (tagged `notice_owner="channel"`).
It applies ONLY to the retryable path: on a hard mismatch (a closed ask) the
channel's re-ask surface is moot, so the ladder always sends the final "question is
closed" notice regardless of this flag.

`params` is the OPTIONAL opaque channel enrichment this inbound reply carries — the
ANSWER-path counterpart of a conversation entry's `params`: a tapped reply id, a template
button payload, a referral. The ladder threads it BOTH
ways with the same seam symmetry — forwarded to the ask's callback door alongside the answer
(landing on `params`, read by
the asking flow beside `answer`) AND, when the reply is instead BRIDGED as a fresh turn,
passed to `accept` as its `params` — so enrichment is never dropped on either arm. The
SAME transport vocabulary (`validate_entry_params`) bounds
it; the platform attaches no meaning and NO TRUST. `None` means no enrichment.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `channel_id` | `str` |
| `our_identity` | `str` |
| `client_address` | `str` |
| `cap_key` | `str` |
| `provider_message_id` | `str` |
| `medium_message_id` | `str \| None` |
| `reply_to_medium_message_id` | `str \| None` |
| `bridge_text` | `str` |
| `owns_retry_notice` | `bool` |
| `params` | `dict[str, str] \| None` |

## LinkOption

`tai42_contract.channels.options.LinkOption`

```python theme={null}
class LinkOption(BaseModel)
```

A tappable link action.

Tapping OPENS `url` (an absolute `http(s)` URL) in the human's
browser — NO message is submitted, distinct from a `ReplyOption`. `label` is the
button text. The URL-button / call-to-action case. Frozen.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `kind` | `Literal['link']` |
| `label` | `str` |
| `url` | `str` |

## Option

`tai42_contract.channels.options.Option`

```python theme={null}
Option = Annotated[ReplyOption | LinkOption, Field(discriminator='kind')]
```

## OptionSection

`tai42_contract.channels.options.OptionSection`

```python theme={null}
class OptionSection(BaseModel)
```

One titled section of a sectioned option list.

`title` is the section header; `rows` are
its entries — a sectioned list holds `ReplyOption` rows ONLY (a tapped row submits its
text; a link action is a button, never a list row). A present `rows` is non-empty. Frozen.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `title` | `str` |
| `rows` | `list[ReplyOption]` |

## ReplyOption

`tai42_contract.channels.options.ReplyOption`

```python theme={null}
class ReplyOption(BaseModel)
```

A tappable suggested reply.

Tapping SUBMITS `text` as the participant's next inbound message —
the quick-reply / list-row case, where the option's own text becomes the turn. `description`
is an OPTIONAL secondary line a sectioned-list row renders under its `text`; a channel that
renders flat buttons (no descriptions) ignores it.

`id` is an OPTIONAL author-set stable identifier for the button/list row. When set, a channel
sends it verbatim on the wire and the participant's tap echoes it back (a channel surfaces the echoed
id to the inbound turn as opaque enrichment — e.g. Slack forwards it as `params.reply_id`);
when `None` the channel mints its own id. Bounded by the platform abuse bound
`OPTION_ID_MAX_CHARS` and a single-line non-blank label; a channel with a tighter id cap
enforces it in its own code. Frozen.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `kind` | `Literal['reply']` |
| `text` | `str` |
| `description` | `str \| None` |
| `id` | `str \| None` |

## ReplyWindow

`tai42_contract.channels.reply_window.ReplyWindow`

```python theme={null}
class ReplyWindow(BaseModel)
```

The free-form reply window a channel keeps for one (our identity, client address) pair.

`state` is one of:

* `"none"` — the pair has no reply window: a free-form send is not limited by time.
* `"closed"` — a window exists for the pair and is not open now (never opened, or expired).
* `"open"` — a free-form send is allowed until `closes_at`.

`closes_at` is set (an aware datetime, kept in UTC and in whole seconds) exactly when
`state` is `"open"` and is `None` otherwise; any other combination raises. A
sub-second close time is rounded down to its second, so the window is never reported
longer than it is and every channel dumps the same `YYYY-MM-DDTHH:MM:SSZ` form. The state
is what the channel knows when it is read; the medium's own rejection of a send outside its
window stays the final check.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `state` | `Literal['open', 'closed', 'none']` |
| `closes_at` | `AwareDatetime \| None` |

## SendOutcome

`tai42_contract.channels.delivery.SendOutcome`

```python theme={null}
class SendOutcome(BaseModel)
```

What a completed channel send reports about itself.

`our_identity` is the identity the message went out from. `address` is the
participant address the medium delivered to, in the same form the channel's inbound
door passes to `accept` as `client_address` (taken from the send response where
the medium reveals that form only there). `message_ids` are the provider ids of the
messages sent, in send order (several when the medium splits a long message, empty
when it exposes no id).

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `our_identity` | `str` |
| `address` | `str` |
| `message_ids` | `list[str]` |

## check\_footer

`tai42_contract.channels.options.check_footer`

```python theme={null}
check_footer(value: str | None) -> str | None
```

A footer is the short trailing line under an interactive message.

None means none; a present value is non-blank and within `NOTIFICATION_FOOTER_MAX_CHARS`.
Raises `ValueError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `str \| None` | — | — |

## check\_header

`tai42_contract.channels.options.check_header`

```python theme={null}
check_header(value: MediaItem | None) -> MediaItem | None
```

A header is a SINGLE display-media item shown above an interactive message.

None means
none; a present item is display media (image/document/video/audio), never a `link` (an
anchor is content, not a header). The item's own url/kind shape is `MediaItem`'s
concern. Raises `ValueError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `MediaItem \| None` | — | — |

## check\_interactive\_composition

`tai42_contract.channels.composition.check_interactive_composition`

```python theme={null}
check_interactive_composition(
    *,
    message: str,
    media: list[MediaItem] | None,
    location: LocationElement | None,
    template: ChannelTemplate | None,
    options: list[Option] | None,
    sections: list[OptionSection] | None,
    schema: dict[str, Any] | None,
    header: MediaItem | None,
    footer: str | None,
    wording: Wording | None,
    has_pages: bool,
    noun: str,
) -> None
```

The shared cross-field rules every option-carrying message carrier enforces.

`ChannelNotification` and `AnswerPart` share these,
so the two can never drift. `noun` names the carrier for the raised messages
(`"notification"` / `"part"`). Rules:

* message is non-blank BY DEFAULT, EXCEPT blank for a CONTENT-ONLY send — a blank message
  carried by non-empty `media` OR a `location` (a caption-less image / a bare pin).
* an interactive surface (`options`, `sections`, `schema`) REQUIRES a non-blank message
  — a choice or a form needs a prompt — so a content-only send carries none of them.
* `options` XOR `sections` — one choice surface (flat buttons OR a sectioned list).
* `schema` is exclusive with both `options` and `sections` — one interactive surface
  (a form's fields OR a choice list), never both.
* `header` and `footer` compose an interactive message, so each REQUIRES `options` or
  `sections` present.
* each per-send `wording` member is admitted only on the surface that draws it — a form
  (`schema`), a flat `options` list, or a sectioned `sections` list (the one admission
  table, `check_wording_for_notification`);
  `wording.form.submit` is refused when the form carries `pages` (`has_pages`).
* `template` is the standalone out-of-window send: exclusive with every other content and
  interactive field (`media`, `location`, `options`, `sections`, `schema`; and
  transitively `header`/`footer`, which require `options`/`sections`).
* a form `schema` declares no top-level property named `__proto__`
  (`check_form_property_names`), the one
  name a form drawn in a browser cannot keep — the same refusal an asked form meets.
* a form `schema`'s date keys make sense
  (`check_form_date_rules`), the same
  build-time date rules an asked form meets.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `message` | `str` | — | — |
| `media` | `list[MediaItem] \| None` | — | — |
| `location` | `LocationElement \| None` | — | — |
| `template` | `ChannelTemplate \| None` | — | — |
| `options` | `list[Option] \| None` | — | — |
| `sections` | `list[OptionSection] \| None` | — | — |
| `schema` | `dict[str, Any] \| None` | — | — |
| `header` | `MediaItem \| None` | — | — |
| `footer` | `str \| None` | — | — |
| `wording` | `Wording \| None` | — | — |
| `has_pages` | `bool` | — | — |
| `noun` | `str` | — | — |

## check\_options

`tai42_contract.channels.options.check_options`

```python theme={null}
check_options(value: list[Option] | None) -> list[Option] | None
```

List-level caps on a flat interactive option list.

None means none; a present list is
non-empty and holds at most `NOTIFICATION_OPTIONS_MAX` entries. Each option's own shape
(reply text / link label+url bounds) is the `ReplyOption`/`LinkOption` concern.
Raises `ValueError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `list[Option] \| None` | — | — |

## check\_sections

`tai42_contract.channels.options.check_sections`

```python theme={null}
check_sections(value: list[OptionSection] | None) -> list[OptionSection] | None
```

List-level caps on a sectioned option list.

None means none; a present list is non-empty,
holds at most `NOTIFICATION_SECTIONS_MAX` sections, and its rows summed across every section
stay within `NOTIFICATION_OPTIONS_MAX` (one message never fans out an unbounded tap set).
Raises `ValueError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `list[OptionSection] \| None` | — | — |


# Connectors (tai42_contract.connectors)
Source: https://docs.tai42.ai/reference/python-sdk/contract-connectors

The ProviderDescriptor a connector plugin declares.

Provider descriptors — declarative shape of a supported third-party.

Pure pydantic models describing a provider, its sub-services, MCP server
endpoints, OAuth endpoints, and client-supplied config fields. Descriptors are
validated when built so a misconfigured provider fails loudly rather than at
first user click. Every model refuses an unknown key (`extra="forbid"`), naming
it, so a misspelled field fails loudly instead of being dropped.

## SLUG\_RE

`tai42_contract.connectors.providers.SLUG_RE`

```python theme={null}
SLUG_RE = re.compile('^[a-z][a-z0-9_]*$')
```

## McpServerDescriptor

`tai42_contract.connectors.providers.McpServerDescriptor`

```python theme={null}
class McpServerDescriptor(BaseModel)
```

MCP server endpoint for one sub-service.

Transport is either `http`/`websocket` (hosted out-of-band, set `url`)
or `stdio` (launched as a child process, set `command` + `args`).
Exactly one configuration is allowed: `url` xor (`command` + `args`).

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `type` | `Literal['http', 'websocket', 'stdio']` |
| `url` | `str \| None` |
| `command` | `str \| None` |
| `args` | `list[str]` |
| `env` | `dict[str, str]` |
| `extra_headers` | `dict[str, str]` |

### Members

#### model\_post\_init

`tai42_contract.connectors.providers.McpServerDescriptor.model_post_init`

```python theme={null}
model_post_init(self, _ctx: Any) -> None
```

Enforce the transport rule: `url` for http/websocket, `command` + `args` for stdio.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `_ctx` | `Any` | — | — |

## ConfigFieldSpec

`tai42_contract.connectors.providers.ConfigFieldSpec`

```python theme={null}
class ConfigFieldSpec(BaseModel)
```

One client-supplied static config value for a no-auth provider.

`target` picks the injection channel and MUST match the server transport
(`env` for stdio, `header` for http/websocket). `secret` flags a value
masked in the UI and never logged; `required` gates connect-time validation.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `key` | `str` |
| `label` | `str` |
| `target` | `Literal['env', 'header']` |
| `required` | `bool` |
| `secret` | `bool` |

## SubServiceDescriptor

`tai42_contract.connectors.providers.SubServiceDescriptor`

```python theme={null}
class SubServiceDescriptor(BaseModel)
```

One sub-service a provider exposes, with its scopes and a single launch path.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `id` | `str` |
| `display_name` | `str` |
| `description` | `str` |
| `scopes` | `list[str]` |
| `mcp_server` | `McpServerDescriptor \| None` |
| `entry_point` | `str \| None` |

## OAuthEndpoints

`tai42_contract.connectors.providers.OAuthEndpoints`

```python theme={null}
class OAuthEndpoints(BaseModel)
```

The OAuth endpoint URLs of a DECLARED provider: authorize, token exchange, and optional revoke.

A provider that carries this block is in declared mode (fixed endpoints, an env client, no
discovery); a `kind == "oauth"` provider without it is in discovered mode, where the engine
reads the endpoints from the authorization server its MCP server names.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `authorize` | `str` |
| `token` | `str` |
| `revoke` | `str \| None` |

## ProviderDescriptor

`tai42_contract.connectors.providers.ProviderDescriptor`

```python theme={null}
class ProviderDescriptor(BaseModel)
```

The universal connector-provider contract, registered from the manifest `connectors` list at boot/reload.

A `kind == "oauth"` provider is in exactly one of two modes. Declared: `oauth` carries the
endpoints and `client_id_env` / `client_secret_env` name the operator's client. Discovered:
`oauth` is unset and the engine discovers the authorization server from the one MCP server all
sub-services share; the client is either the env client pinned by `issuer` to the authorization
server it is registered with, or (all three unset) a stored client.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `id` | `str` |
| `display_name` | `str` |
| `description` | `str` |
| `kind` | `Literal['oauth', 'none']` |
| `origin` | `Literal['system', 'community']` |
| `category` | `str` |
| `oauth` | `OAuthEndpoints \| None` |
| `client_id_env` | `str \| None` |
| `client_secret_env` | `str \| None` |
| `issuer` | `str \| None` |
| `sub_services` | `dict[str, SubServiceDescriptor]` |
| `pkg_manager` | `Literal['uvx', 'npx'] \| None` |
| `pkg_version` | `str \| None` |
| `config_fields` | `list[ConfigFieldSpec]` |
| `extra_authorize_params` | `dict[str, str]` |

### Members

#### icon\_url

`tai42_contract.connectors.providers.ProviderDescriptor.icon_url`

```python theme={null}
icon_url: str | None = None
```

An `https://` URL to the provider's icon, or `None` for none; http, relative, or empty is
rejected. The catalog serves this value verbatim as a brand mark, the same
rule the plugin spec's `icon` enforces.

#### is\_discovered

`tai42_contract.connectors.providers.ProviderDescriptor.is_discovered`

```python theme={null}
is_discovered: bool
```

Whether this is an OAuth provider in discovered mode (no declared `oauth` endpoints).

#### discovery\_url

`tai42_contract.connectors.providers.ProviderDescriptor.discovery_url`

```python theme={null}
discovery_url: str
```

The one MCP server URL every sub-service of a discovered provider shares.

Raises `RuntimeError` for a declared or no-auth provider (a caller bug: only a discovered
provider is discovered).


# Extensions (tai42_contract.extensions)
Source: https://docs.tai42.ai/reference/python-sdk/contract-extensions

The ExtensionKind taxonomy and extension base surface.

Extension contracts.

`ExtensionKind` is the enum of tool-extension kinds (Wrapper / Transformer /
Backend). Each kind carries its distinguishing rules as explicit properties —
`multiple` (cardinality), `preserves_schema` and `declares_schema` (the
input-schema rule), `preserves_output_shape` (whether a minted branch may
inherit the base tool's output schema), and `relocates_execution` (whether the
kind moves the tool body to another process) — so generic machinery keys off a
property, never off `kind is WRAPPER`. The per-kind extension shape is in
`tai42_contract.extensions.kinds`.

## ExtensionKind

`tai42_contract.extensions.ExtensionKind`

```python theme={null}
class ExtensionKind(StrEnum)
```

The three tool-extension kinds and their per-kind properties.

Every kind branches by rename: an extension mints a NEW-named variant tool
bound alongside the original, and a stacked combo (`[a, b]`) binds one
variant per prefix (`tool`, `tool_a`, `tool_a_b`). No kind replaces a
tool in place.

* `WRAPPER` — presents the wrapped tool's input schema unchanged (minus its
  own declared `reserved_params`); stackable.
* `TRANSFORMER` — presents its OWN composed input schema (a concrete
  makefun-presented signature, never bare `*args/**kwargs`); stackable.
* `BACKEND` — one execution-backend strategy per tool (`multiple=False`);
  no input-schema rule; relocates the tool body's execution to a worker
  process (`relocates_execution`).

**Attributes**

| Attribute | Type |
| - | - |
| `WRAPPER` | — |
| `TRANSFORMER` | — |
| `BACKEND` | — |

### Members

#### multiple

`tai42_contract.extensions.ExtensionKind.multiple`

```python theme={null}
multiple: bool
```

Whether a single tool may carry more than one extension of this kind.

#### preserves\_schema

`tai42_contract.extensions.ExtensionKind.preserves_schema`

```python theme={null}
preserves_schema: bool
```

Whether an extension of this kind must present the extended tool's input schema unchanged.

Parameter names/types stay identical; the tool NAME always changes —
every extension branches to a new-named tool.

#### declares\_schema

`tai42_contract.extensions.ExtensionKind.declares_schema`

```python theme={null}
declares_schema: bool
```

Whether an extension of this kind must present its OWN concrete input schema.

The signature is a real makefun-presented one, never bare
`*args/**kwargs`.

#### relocates\_execution

`tai42_contract.extensions.ExtensionKind.relocates_execution`

```python theme={null}
relocates_execution: bool
```

Whether an extension of this kind moves the tool body's execution to another process.

A BACKEND swaps the execution strategy for a worker (the
wrapped callable is submitted and runs there, not in the process that
received the call); a WRAPPER and a TRANSFORMER execute the body
in-process, inside their own frame.

This drives the stacking-order rule the apply site enforces: an
extension that `requires_body_locality` (its wrapper only works in the
process running the tool body, e.g. a proxy layer routing egress through
a task-scoped contextvar) must bind INSIDE any relocating extension, so
its wrapper travels with the body to the worker. Bound outside, the
relocating layer ships only the inner callable and the locality-requiring
wrapper stays behind in the submitting process, silently not applying.

#### preserves\_output\_shape

`tai42_contract.extensions.ExtensionKind.preserves_output_shape`

```python theme={null}
preserves_output_shape: bool
```

Whether an extension of this kind returns the extended tool's result shape unchanged.

A branch it mints may then inherit the base tool's OUTPUT schema. This is
an OUTPUT-schema concern, distinct from `preserves_schema` (which is
about the INPUT schema): a WRAPPER returns the wrapped tool's result
unchanged and a BACKEND swaps the execution strategy but returns the same
output shape (both preserve), while a TRANSFORMER reshapes the result
(does not preserve).


# Interaction outcomes (tai42_contract.interactions)
Source: https://docs.tai42.ai/reference/python-sdk/contract-interactions

The typed outcomes a resumed run returns: suspended, buffered, and failed.

The `ask` answer and interaction-state models.

`InteractionResponse` is the validated answer pushed onto the reply channel;
`AskAnswer` is the one value a synchronous asker receives;
`InteractionState` is the mutable record the answer endpoint reads;
`SuspendedInteraction` is the sentinel an `async` ask returns in place of an answer.

## ELICIT\_META\_REPLY\_TO

`tai42_contract.interactions.models.response.ELICIT_META_REPLY_TO`

```python theme={null}
ELICIT_META_REPLY_TO: Final = 'tai42/reply_to'
```

## InteractionResponse

`tai42_contract.interactions.models.response.InteractionResponse`

```python theme={null}
class InteractionResponse(BaseModel)
```

The answer. Validated server-side before it wakes the caller.

`params` is the OPTIONAL opaque channel enrichment carried WITH the answer — the answer-path
counterpart of the bridge path's `params` and a
conversation entry's `params`: when a tap/reply that ANSWERS a pending ask also carries
channel-specific context (a tapped reply id, a template button payload, a referral) the
channel encodes it as string entries here. The SAME transport vocabulary
(`validate_entry_params`) bounds it as every params seam;
the platform attaches no meaning and NO TRUST. `None` means no enrichment — a plain answer.
The asker receives it as is, beside `answer` (`AskAnswer` and the continuation
payload).

`medium_message_id` is the id the medium gave the participant's reply message, the one a
later quote names; `None` when the answer did not arrive as a message on a medium (an
operator or caller answer) or the medium has no such id.

`reply_to_medium_message_id` is the medium's id of the message the answering reply quoted;
`None` when it quoted none or the answer did not arrive over a channel. It holds the id only,
never the quoted text: the platform resolves the text from the conversation record and hands
it to the asker as `reply_to`, beside `answer`.

**Attributes**

| Attribute | Type |
| - | - |
| `interaction_id` | `str` |
| `answer` | `Any` |
| `answered_by` | `str` |
| `answered_at` | `datetime` |
| `params` | `dict[str, str] \| None` |
| `medium_message_id` | `str \| None` |
| `reply_to_medium_message_id` | `str \| None` |

## AskAnswer

`tai42_contract.interactions.models.response.AskAnswer`

```python theme={null}
class AskAnswer(BaseModel)
```

The one value a synchronous asker receives: the answer, the message it quoted, and its params.

`answer` is the answer value exactly as the answering party gave it; on a sensitive ask it is
the `SecretValue` wrapping it, held by reference, so dumping this
value to JSON refuses loudly as a dump of the bare `SecretValue` does. The answer is never
changed or merged with the quote or the params.

`reply_to` is the message the answering reply quoted, as the platform resolved it from the
conversation record; `None` when the reply quoted none or the answer did not come over a
channel. `params` is the channel's opaque enrichment of the answering tap or reply
(`InteractionResponse.params`, the same vocabulary, no platform meaning), passed through
as is; `None` when the answer carried none. Frozen.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `answer` | `Any` |
| `reply_to` | `ReplyTo \| None` |
| `params` | `dict[str, str] \| None` |

## InteractionState

`tai42_contract.interactions.models.response.InteractionState`

```python theme={null}
class InteractionState(BaseModel)
```

Mutable companion to the immutable stream entry, keyed by interaction id.

**Attributes**

| Attribute | Type |
| - | - |
| `status` | `Literal['pending', 'answered']` |
| `group_id` | `str` |
| `request` | `InteractionRequest` |
| `response` | `InteractionResponse \| None` |

## SuspendedInteraction

`tai42_contract.interactions.models.response.SuspendedInteraction`

```python theme={null}
class SuspendedInteraction(BaseModel)
```

The sentinel an `async` ask returns in place of an answer.

Any async-suspending tool returns it to signal the caller was parked, keyed by
`interaction_id` so the resume path can find the parked question. Generic:
a resuming driver's resume state is keyed by this id, not carried here.

**Attributes**

| Attribute | Type |
| - | - |
| `interaction_id` | `str` |
| `expiry_at` | `datetime \| None` |
| `resume_owner` | `str \| None` |
| `interaction_ids` | `list[str]` |
| `caller_interaction_ids` | `list[str]` |

## ResumeBuffered

`tai42_contract.interactions.models.response.ResumeBuffered`

```python theme={null}
class ResumeBuffered(BaseModel)
```

A resume that did NOT drive its super-step to a terminal: sibling asks are still open.

One super-step of a held run can park SEVERAL asks in parallel. Answering one of them
buffers that answer and leaves the step suspended until the last sibling resolves. A resuming
driver returns this in place of a terminal to say exactly that: `remaining_ids` are the
still-unanswered asks of the same step. It is NOT terminal — the platform's delivery chokepoint
delivers nothing for it (the run stays parked), and `visit` normalises it to the caller/user
partition of the remaining ids. Generic: it names interaction ids only, no driver
or engine state. Kept by TYPE through the run-tool seam alongside `SuspendedInteraction` so a
caller recognises a still-suspended step rather than mistaking it for a terminal result.

**Attributes**

| Attribute | Type |
| - | - |
| `remaining_ids` | `list[str]` |

## RunFailed

`tai42_contract.interactions.models.response.RunFailed`

```python theme={null}
class RunFailed(BaseModel)
```

A run's failed terminal returned across a chain fire; `outcome` is the failing driver's opaque mapping.

A driver that resumes another driver's run through a chain-delivery tool reads the failure by
TYPE, never by a status word inside the outcome: the outcome stays the failing driver's own
JSON mapping, carried whole. A continuation face raises
`RunTerminalFailed` with it, so the platform delivers FAILED.

`reply` is the optional participant-facing text a conversation door shows in place of its
fixed failure line, under the same rules as `RunTerminalFailed`'s
`reply`: the platform never inspects or changes it, and the target that sets it owns that it
is safe for the participant. `None` means no reply.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `outcome` | `dict[str, Any]` |
| `reply` | `ReplyText \| None` |


# Manifest (tai42_contract.manifest)
Source: https://docs.tai42.ai/reference/python-sdk/contract-manifest

The manifest model a server loads at startup.

Manifest contract: `Manifest`, the `*Config` models, and the filter-predicate signatures.

The `*Config` models include the transport config `TaiMCPConfig`.

The impl methods that build the derived lookup maps and run the include/exclude
filtering (`model_post_init` + the private `_build_*`/`_should_include`
helpers) are logic and stay with the impl — only the field shape, the model
validators, and the public predicate/query signatures are the contract.

## AgentsConfig

`tai42_contract.manifest.AgentsConfig`

```python theme={null}
class AgentsConfig(BaseConfig)
```

An agents block: a `module` import path plus selection config.

Agents carry no clip-on extensions, so an `extensions` key here is refused as
an unknown key, like any other (`BaseConfig`'s `extra="forbid"`).

**Attributes**

| Attribute | Type |
| - | - |
| `module` | `str` |

## ApiToolsConfig

`tai42_contract.manifest.ApiToolsConfig`

```python theme={null}
class ApiToolsConfig(ExtensionsConfigMixin)
```

Curates the MCP tool surface projected from the operations layer.

A single app-owned block, so it carries no `title` and is deliberately NOT
a `BaseConfig` subclass. `include`/`exclude` name operations to project
or suppress; `expose_destructive` gates destructive-flagged operations; the
`extensions` map (from the mixin) attaches extension combos to projected
operations. Unlike `BaseConfig`, a name appearing in BOTH `include` and
`exclude` is a loud validation error — this stricter rule is unique to this
config and is never retrofitted onto other configs.

**Attributes**

| Attribute | Type |
| - | - |
| `enabled` | `bool` |
| `expose_destructive` | `bool` |
| `include` | `list[str]` |
| `exclude` | `list[str]` |

## BaseConfig

`tai42_contract.manifest.BaseConfig`

```python theme={null}
class BaseConfig(BaseModel)
```

Shared config fields: a `title` plus `include`/`exclude` selection lists.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `title` | `str` |
| `include` | `list[str]` |
| `exclude` | `list[str]` |

## ExtensionElement

`tai42_contract.manifest.ExtensionElement`

```python theme={null}
ExtensionElement = str | dict[str, Any]
```

## ExtensionsConfigMixin

`tai42_contract.manifest.ExtensionsConfigMixin`

```python theme={null}
class ExtensionsConfigMixin(BaseModel)
```

Carries the `extensions` attachment map for config kinds that support clip-on extensions.

Mixed into `ToolsConfig` and `TaiMCPConfig`.

`extensions` maps a tool base-name to the extension combo(s) attached to
it, applied AFTER selection and independent of `include`/`exclude`. The
stored shape is always `tool -> list-of-combos`
(`dict[str, list[list[ExtensionElement]]]`) so resolution reads ONE shape
regardless of how the YAML was written; each combo element is an extension
name or a `{"name", "config"}` mapping binding author config to it. The
normalizing validator wraps a flat combo and rejects malformed input loudly.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `extensions` | `dict[str, list[list[ExtensionElement]]]` |

### Members

#### normalize\_extensions

`tai42_contract.manifest.ExtensionsConfigMixin.normalize_extensions`

```python theme={null}
normalize_extensions(cls, value: object) -> dict[str, list[list[ExtensionElement]]]
```

Normalize each value to a list of combos and reject malformed input loudly.

No silent coercion.

A flat combo value is a single combo and is wrapped
(`{weather: [chain]}` -> `{"weather": [["chain"]]}`); a list-of-combos
value is kept as multiple combos. A combo element is an extension name or
a `{"name", "config"}` mapping (author-bound config). This enforces
SHAPE only: it does NOT check that the extension names are registered
(`ExtensionRegistry`'s job) or that the tool is selected
(`missing_tools`' job).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `object` | — | — |

## MCPConfig

`tai42_contract.manifest.MCPConfig`

```python theme={null}
class MCPConfig(BaseModel)
```

Transport config for one MCP server: exactly one of `url`/`uds`/`command`.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `type` | `str \| None` |
| `url` | `str \| None` |
| `uds` | `str \| None` |
| `command` | `str \| None` |
| `args` | `list[str]` |
| `headers` | `dict[str, str]` |
| `env` | `dict[str, str]` |

### Members

#### normalize\_args

`tai42_contract.manifest.MCPConfig.normalize_args`

```python theme={null}
normalize_args(cls, value: object) -> list[str]
```

Coerce a `None` `args` value to an empty list.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `object` | — | — |

#### normalize\_dict\_values

`tai42_contract.manifest.MCPConfig.normalize_dict_values`

```python theme={null}
normalize_dict_values(cls, value: object) -> dict[str, str]
```

Coerce `None` to an empty dict and stringify values, failing loudly on a `None` value.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `object` | — | — |

## Manifest

`tai42_contract.manifest.Manifest`

```python theme={null}
class Manifest(BaseModel)
```

The whole application manifest: tool/agent/MCP blocks, module lists, and derived maps.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `tools` | `list[ToolsConfig]` |
| `agents` | `list[AgentsConfig]` |
| `mcp` | `list[TaiMCPConfig]` |
| `middlewares_modules` | `list[str]` |
| `routers_modules` | `list[str]` |
| `default_routers` | `Literal['all', 'api', 'none']` |
| `extensions_modules` | `list[str]` |
| `lifecycle_modules` | `list[str]` |
| `connectors` | `list[ProviderDescriptor]` |
| `webhook_verifier_modules` | `list[str]` |
| `channel_modules` | `list[str]` |
| `backend_module` | `str \| None` |
| `storage_module` | `str \| None` |
| `monitoring_module` | `str \| None` |
| `sandbox_module` | `str \| None` |
| `static_dir` | `str \| None` |
| `studio_plugins` | `list[str]` |
| `user_tools` | `set[str]` |
| `api_tools` | `ApiToolsConfig` |
| `tools_list` | `set[str] \| None` |
| `tool_extensions` | `dict[str, list[list[ExtensionElement]]] \| None` |
| `tools_map` | `dict[str, ToolsConfig] \| None` |
| `agents_map` | `dict[str, AgentsConfig] \| None` |
| `mcp_map` | `dict[str, TaiMCPConfig] \| None` |
| `tools_module_title_map` | `dict[str, str] \| None` |
| `include_module_tools_map` | `dict[str, frozenset[str]] \| None` |
| `exclude_module_tools_map` | `dict[str, frozenset[str]] \| None` |
| `include_module_agents_map` | `dict[str, frozenset[str]] \| None` |
| `exclude_module_agents_map` | `dict[str, frozenset[str]] \| None` |
| `include_title_mcp_tools_map` | `dict[str, frozenset[str]] \| None` |
| `exclude_title_mcp_tools_map` | `dict[str, frozenset[str]] \| None` |

### Members

#### should\_include\_tool

`tai42_contract.manifest.Manifest.should_include_tool`

```python theme={null}
should_include_tool(self, name: str, module: str) -> bool
```

Whether tool `name` from `module` survives the include/exclude filter.

Also records the decision on the matching config.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `module` | `str` | — | — |

#### should\_include\_agent

`tai42_contract.manifest.Manifest.should_include_agent`

```python theme={null}
should_include_agent(self, name: str, module: str) -> bool
```

Whether agent `name` from `module` survives the include/exclude filter.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `module` | `str` | — | — |

#### should\_include\_mcp\_tool

`tai42_contract.manifest.Manifest.should_include_mcp_tool`

```python theme={null}
should_include_mcp_tool(self, name: str, title: str) -> bool
```

Whether MCP tool `name` under `title` survives the include/exclude filter.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `title` | `str` | — | — |

#### replace\_mcp

`tai42_contract.manifest.Manifest.replace_mcp`

```python theme={null}
replace_mcp(self, mcp: list[TaiMCPConfig]) -> None
```

Swap the MCP rows and rebuild the derived maps (surgical reload).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `mcp` | `list[TaiMCPConfig]` | — | — |

#### live\_manifest

`tai42_contract.manifest.Manifest.live_manifest`

```python theme={null}
live_manifest: Manifest
```

A deep copy whose `tools`/`agents`/`mcp` reflect the live config maps.

The maps are post-filter.

#### find\_title

`tai42_contract.manifest.Manifest.find_title`

```python theme={null}
find_title(self, module: str) -> str
```

Map a module path to the owning tool config's title (longest prefix).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `module` | `str` | — | — |

## TaiMCPConfig

`tai42_contract.manifest.TaiMCPConfig`

```python theme={null}
class TaiMCPConfig(BaseConfig, ExtensionsConfigMixin)
```

An MCP block: a transport `config` plus optional managed-connector binding.

**Attributes**

| Attribute | Type |
| - | - |
| `config` | `MCPConfig` |
| `managed` | `ConnectorRef \| None` |

### Members

#### is\_managed

`tai42_contract.manifest.TaiMCPConfig.is_managed`

```python theme={null}
is_managed: bool
```

Whether this MCP block is backed by a managed connector.

## ToolsConfig

`tai42_contract.manifest.ToolsConfig`

```python theme={null}
class ToolsConfig(BaseConfig, ExtensionsConfigMixin)
```

A tools block: a `module` import path plus selection and extension config.

**Attributes**

| Attribute | Type |
| - | - |
| `module` | `str` |

## normalize\_extension\_element

`tai42_contract.manifest.normalize_extension_element`

```python theme={null}
normalize_extension_element(member: object) -> ExtensionElement
```

Validate one combo member and return it in canonical form, raising `ValueError` when malformed.

A non-empty `str` is an extension name with no bound config. A `dict` binds author config
and must carry a non-empty string `name` (registration is checked later) and a `config`
mapping, with no other keys.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `member` | `object` | — | — |


# Monitoring (tai42_contract.monitoring)
Source: https://docs.tai42.ai/reference/python-sdk/contract-monitoring

The MonitoringReader and MonitoringWriter protocols.

The read/query half of the monitoring contract.

Implement only if the backend has a read API. A read-incapable backend still
exposes a `reader` object, but its methods raise `MonitoringReadNotSupportedError`
on call (never a silent no-op).

OpenTelemetry has no read/query standard — each backend invents its own read
surface — so this face is the abstraction's real value.

## MonitoringReader

`tai42_contract.monitoring.reader.MonitoringReader`

```python theme={null}
class MonitoringReader(Protocol)
```

Query totals/analytics and the runtime span window.

### Members

#### metrics\_capability

`tai42_contract.monitoring.reader.MonitoringReader.metrics_capability`

```python theme={null}
metrics_capability(self) -> MetricsCapability
```

Declare which neutral measures and dimensions `query_metrics` serves.

A pure capability declaration (no I/O), so a caller can tell a panel the
backend cannot serve from one it served empty, WITHOUT issuing a query that
swallows the difference. `query_metrics` raises
`MonitoringReadNotSupportedError` for anything outside this set.

#### list\_capability

`tai42_contract.monitoring.reader.MonitoringReader.list_capability`

```python theme={null}
list_capability(self) -> ListCapability
```

Declare which sorts `list_traces` serves and which filters each sort cannot combine with.

A pure capability declaration (no I/O), so a caller offers only the sorts and
filter combinations the backend serves. `list_traces` raises
`MonitoringReadNotSupportedError` for anything outside it.

#### max\_page\_size

`tai42_contract.monitoring.reader.MonitoringReader.max_page_size`

```python theme={null}
max_page_size(self) -> int
```

Declare the largest `limit` one `list_traces` call accepts.

A pure declaration (no I/O). A `limit` above it raises `ValueError`.

#### query\_metrics

`tai42_contract.monitoring.reader.MonitoringReader.query_metrics`

```python theme={null}
async query_metrics(self, query: MetricsQuery) -> MetricsResult
```

Totals / analytics screen — server-side aggregation.

Aggregates the requested `Measure` set grouped by the requested
`Dimension` set over the query window. A measure or dimension outside
`metrics_capability` raises `MonitoringReadNotSupportedError` — never
a silent zero.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `query` | `MetricsQuery` | — | — |

#### list\_spans\_in\_window

`tai42_contract.monitoring.reader.MonitoringReader.list_spans_in_window`

```python theme={null}
async list_spans_in_window(
    self,
    t0: datetime,
    t1: datetime,
    *,
    run: str | None = None,
    kind: SpanKind | None = None,
    filter_: MonitoringFilter | None = None,
    order_by: OrderBy | None = None,
) -> list[SpanWindowItem]
```

The smallest spans that ran in the half-open window `[t0, t1)`.

CONTRACT GUARANTEE: exactly one item per tool execution in the
window. Every reader performs this tool-granularity selection — it is
not an optional filter. A reader selects steps by the producers' marker:
an observation whose metadata `tai42.step_role` is `grouping` or
`sub_step` is never an item; generations and events are never items.

`run` scopes to a single run (one trace); `None` = all runs in the
window. `kind` narrows WITHIN the tool-granularity set (never widens
or overrides the guarantee). `filter` applies the neutral
`MonitoringFilter` clauses (tags live here, not as a discrete param).
`order_by` sorts the result; omitted ⇒ newest-first (`start` desc).
An unsupported `order_by.field` or filter clause raises
`MonitoringReadNotSupportedError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `t0` | `datetime` | — | — |
| `t1` | `datetime` | — | — |
| `run` | `str \| None` | `None` | — |
| `kind` | `SpanKind \| None` | `None` | — |
| `filter_` | `MonitoringFilter \| None` | `None` | — |
| `order_by` | `OrderBy \| None` | `None` | — |

#### get\_trace

`tai42_contract.monitoring.reader.MonitoringReader.get_trace`

```python theme={null}
async get_trace(self, trace_id: str) -> MonitoringTrace
```

Fetch one COMPLETE trace (top-level attrs + every observation, with full input/output).

Used for replay / evaluation / normalization. Always returns a trace or raises — never `None`. An absent trace
raises `TraceNotFoundError`; a transient/backend failure (e.g. a timeout)
propagates its error so the caller sees the failure and may retry.
Distinct from `list_spans_in_window` (trimmed dashboard units).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `trace_id` | `str` | — | — |

#### get\_observation

`tai42_contract.monitoring.reader.MonitoringReader.get_observation`

```python theme={null}
async get_observation(self, trace_id: str, observation_id: str) -> MonitoringObservation
```

One observation of a trace, with its full input/output.

An absent observation raises `ObservationNotFoundError`; an absent trace raises
`TraceNotFoundError`; any other backend failure propagates.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `trace_id` | `str` | — | — |
| `observation_id` | `str` | — | — |

#### list\_traces

`tai42_contract.monitoring.reader.MonitoringReader.list_traces`

```python theme={null}
async list_traces(
    self,
    *,
    from_timestamp: datetime | None = None,
    to_timestamp: datetime | None = None,
    limit: int | None = None,
    page: int | None = None,
    filter_: MonitoringFilter | None = None,
    order_by: OrderBy | None = None,
) -> list[MonitoringTraceSummary]
```

List run SUMMARIES matching the filters: one row per trace.

Built from the backend's list surface plus its batched aggregates — never a per-trace body.
`get_trace` is the only body door. A malformed backend row fails the page loudly (never kept
as a partial row nor silently skipped).

`from_timestamp` / `to_timestamp` bound the trace timestamp to the
half-open window `[from, to)`; either may be omitted for an open end.
`filter` applies the neutral `MonitoringFilter` clauses (tags live
here, not as a discrete param). `order_by` sorts the result; omitted ⇒
newest-first (`timestamp` desc). The sortable fields and the filters
each sort cannot combine with are declared by `list_capability`; a sort
or combination outside it, or another unsupported filter clause, raises
`MonitoringReadNotSupportedError`. A `limit` above `max_page_size()`
raises `ValueError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `from_timestamp` | `datetime \| None` | `None` | — |
| `to_timestamp` | `datetime \| None` | `None` | — |
| `limit` | `int \| None` | `None` | — |
| `page` | `int \| None` | `None` | — |
| `filter_` | `MonitoringFilter \| None` | `None` | — |
| `order_by` | `OrderBy \| None` | `None` | — |

The write/emit half of the monitoring contract.

**FAIL-SAFE INVARIANT**

The EMIT methods (`open_span`, `start_span`, `record_span`, `create_event`,
`update_current_span`, `trace_attributes`) and the `Span`-handle methods
(`Span.update`, `Span.set_trace_metadata`, `Span.end`) catch their own errors —
they MUST NOT raise into application code. A monitoring outage cannot be allowed to
break a flow, so call sites need NO `try/except` around them. Fail-safe never means
silent: every caught failure is logged at ERROR and counted in
`export_health().records_failed`. (The one precondition that DOES raise is
`record_span` with no `trace_id` — a caller bug, not a backend outage.) The
module-level `attribute_run` helper composes `writer` over
`trace_attributes`, inheriting that method's guarantee.

The NON-emit methods are NOT fail-safe and propagate errors loudly: `flush` /
`shutdown` (fork-safety must not be silently skipped) and `disable` (a backend may
legitimately no-op it — doing nothing successfully — but a real FAILURE inside it must
raise, never be swallowed).

`current_trace_id()` / `current_span_id()` / `is_recording()` / `export_health()`
are queries: they never raise.

**MASKING**

A writer renders every `SecretValue` found anywhere in a record's input, output or
metadata as `SECRET_PLACEHOLDER`; callers never mask for monitoring.

**RESERVED MARKERS**

A recorded value holds a one-key object whose key starts with `RESERVED_KEY_PREFIX`
only where the writer rendered a marker (a `{"$tai42_ref": …}` reference, the
`{"$tai42_unrecorded": true}` statement, the writer's own byte-string and unencodable
forms). A user value carrying such an object is refused by the writer, so a marker read
back from a backend is never user data.

**AMBIENT vs EXPLICIT context**

`trace_context` is OPTIONAL. `None` = emit into the CURRENT (ambient) context —
what the no-handle sites use (plain functions with no trace handle). An explicit
`TraceContext` is passed only when one is held (e.g. a downstream/parent span held by
a run driver).

## RUN\_ATTRIBUTION\_TRACE\_NAME

`tai42_contract.monitoring.writer.RUN_ATTRIBUTION_TRACE_NAME`

```python theme={null}
RUN_ATTRIBUTION_TRACE_NAME = 'run'
```

## RUN\_VERSION\_METADATA\_KEY

`tai42_contract.monitoring.writer.RUN_VERSION_METADATA_KEY`

```python theme={null}
RUN_VERSION_METADATA_KEY = 'run_version'
```

## MonitoringWriter

`tai42_contract.monitoring.writer.MonitoringWriter`

```python theme={null}
class MonitoringWriter(Protocol)
```

Emit traces/spans/events, report export health, and manage lifecycle.

Every backend implements this face.

### Members

#### open\_span

`tai42_contract.monitoring.writer.MonitoringWriter.open_span`

```python theme={null}
open_span(
    self,
    *,
    name: str,
    kind: SpanKind,
    trace_context: TraceContext | None = None,
    input_: Any = None,
    model: str | None = None,
    model_parameters: dict[str, Any] | None = None,
    metadata: dict[str, Any] | None = None,
    start_time: datetime | None = None,
    activate: bool = False,
) -> Span
```

Open a span (started at `start_time`, else now) and return its handle; `Span.end` records it.

`activate=True` makes the span the current span of the calling context until
`end()` restores the previous one (`end()` must run in the same context).
`model` / `model_parameters` carry generation-span detail. Under an active
`disable()` block the handle is a no-op one.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `kind` | `SpanKind` | — | — |
| `trace_context` | `TraceContext \| None` | `None` | — |
| `input_` | `Any` | `None` | — |
| `model` | `str \| None` | `None` | — |
| `model_parameters` | `dict[str, Any] \| None` | `None` | — |
| `metadata` | `dict[str, Any] \| None` | `None` | — |
| `start_time` | `datetime \| None` | `None` | — |
| `activate` | `bool` | `False` | — |

#### start\_span

`tai42_contract.monitoring.writer.MonitoringWriter.start_span`

```python theme={null}
start_span(
    self,
    *,
    name: str,
    kind: SpanKind,
    trace_context: TraceContext | None = None,
    input_: Any = None,
    model: str | None = None,
    model_parameters: dict[str, Any] | None = None,
    metadata: dict[str, Any] | None = None,
) -> AbstractContextManager[Span]
```

Open an activated span for the duration of the block, yielding its handle.

Equals `open_span(activate=True)` with `end()` on exit; calling `end()`
inside the block is a caller bug. `model_parameters` is open-time only;
`model` and `usage` can be amended later via `Span.update`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `kind` | `SpanKind` | — | — |
| `trace_context` | `TraceContext \| None` | `None` | — |
| `input_` | `Any` | `None` | — |
| `model` | `str \| None` | `None` | — |
| `model_parameters` | `dict[str, Any] \| None` | `None` | — |
| `metadata` | `dict[str, Any] \| None` | `None` | — |

#### record\_span

`tai42_contract.monitoring.writer.MonitoringWriter.record_span`

```python theme={null}
record_span(
    self,
    *,
    name: str,
    kind: SpanKind,
    start: datetime,
    end: datetime,
    trace_context: TraceContext,
    input_: Any = None,
    output: Any = None,
    level: MonitoringLevel | None = None,
    status_message: str | None = None,
    model: str | None = None,
    usage: TokenUsage | None = None,
    metadata: dict[str, Any] | None = None,
) -> None
```

Record an already-closed span with EXPLICIT `start` / `end` times.

For a span whose execution window cannot be timed live in-process — work that
ran across a pause and is reported afterwards. `trace_context.trace_id` is
REQUIRED — the explicit-time path has no ambient context to fall back to, so a
missing `trace_id` RAISES (a caller bug); `parent_span_id` nests the span.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `kind` | `SpanKind` | — | — |
| `start` | `datetime` | — | — |
| `end` | `datetime` | — | — |
| `trace_context` | `TraceContext` | — | — |
| `input_` | `Any` | `None` | — |
| `output` | `Any` | `None` | — |
| `level` | `MonitoringLevel \| None` | `None` | — |
| `status_message` | `str \| None` | `None` | — |
| `model` | `str \| None` | `None` | — |
| `usage` | `TokenUsage \| None` | `None` | — |
| `metadata` | `dict[str, Any] \| None` | `None` | — |

#### create\_event

`tai42_contract.monitoring.writer.MonitoringWriter.create_event`

```python theme={null}
create_event(
    self,
    *,
    name: str,
    level: MonitoringLevel = DEFAULT_LEVEL,
    trace_context: TraceContext | None = None,
    input_: Any = None,
    output: Any = None,
    status_message: str | None = None,
    metadata: dict[str, Any] | None = None,
) -> RecordId | None
```

Record a point-in-time event carrying `input` / `output`.

Returns the event's `RecordId` so a producer can reference its values;
`None` when disabled, when the writer records nothing, or when the record failed.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `level` | `MonitoringLevel` | `DEFAULT_LEVEL` | — |
| `trace_context` | `TraceContext \| None` | `None` | — |
| `input_` | `Any` | `None` | — |
| `output` | `Any` | `None` | — |
| `status_message` | `str \| None` | `None` | — |
| `metadata` | `dict[str, Any] \| None` | `None` | — |

#### update\_current\_span

`tai42_contract.monitoring.writer.MonitoringWriter.update_current_span`

```python theme={null}
update_current_span(
    self,
    *,
    level: MonitoringLevel | None = None,
    status_message: str | None = None,
    metadata: dict[str, Any] | None = None,
    input_: Any = None,
    output: Any = None,
) -> None
```

Amend the CURRENT span without opening a new one.

Targets the span of the nearest enclosing activated `open_span` / `start_span`.
`metadata` is MERGED key-wise into the metadata given so far (a later value for a
key wins). Per-generation token/cost is recorded via `Span.update`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `level` | `MonitoringLevel \| None` | `None` | — |
| `status_message` | `str \| None` | `None` | — |
| `metadata` | `dict[str, Any] \| None` | `None` | — |
| `input_` | `Any` | `None` | — |
| `output` | `Any` | `None` | — |

#### trace\_attributes

`tai42_contract.monitoring.writer.MonitoringWriter.trace_attributes`

```python theme={null}
trace_attributes(
    self,
    *,
    name: str | None = None,
    tags: list[str] | None = None,
    metadata: dict[str, Any] | None = None,
    user_id: str | None = None,
    session_id: str | None = None,
) -> AbstractContextManager[None]
```

Set trace-level name/tags/metadata on every span started inside the block.

`user_id` / `session_id` set the backend's native identity dimensions when
supplied; `None` leaves each unset. A ROOT version is carried inside
`metadata` under `RUN_VERSION_METADATA_KEY` (not a discrete parameter) so
a backend without a native version dimension keeps it as ordinary metadata.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str \| None` | `None` | — |
| `tags` | `list[str] \| None` | `None` | — |
| `metadata` | `dict[str, Any] \| None` | `None` | — |
| `user_id` | `str \| None` | `None` | — |
| `session_id` | `str \| None` | `None` | — |

#### current\_trace\_id

`tai42_contract.monitoring.writer.MonitoringWriter.current_trace_id`

```python theme={null}
current_trace_id(self) -> str | None
```

The active ambient trace id, or `None` if no trace is active.

Used to gate conditional emits (`if writer.current_trace_id():`) so none fire
outside a trace.

#### current\_span\_id

`tai42_contract.monitoring.writer.MonitoringWriter.current_span_id`

```python theme={null}
current_span_id(self) -> str | None
```

The current span's id (16 lower-hex), or `None` when no span is current.

#### is\_recording

`tai42_contract.monitoring.writer.MonitoringWriter.is_recording`

```python theme={null}
is_recording(self) -> bool
```

Whether this writer records anything; `False` lets producers skip all recording work.

#### export\_health

`tai42_contract.monitoring.writer.MonitoringWriter.export_health`

```python theme={null}
export_health(self) -> MonitoringExportHealth
```

A snapshot of everything this writer could not deliver; no I/O.

Counted per PROCESS: a forked child's counters start at zero, so a child never
re-counts what its parent counted.

#### set\_health\_listener

`tai42_contract.monitoring.writer.MonitoringWriter.set_health_listener`

```python theme={null}
set_health_listener(self, listener: Callable[[MonitoringExportHealth], None] | None) -> None
```

Install (`None` removes) the listener called with `export_health()` after every flush.

The writer calls `listener(self.export_health())` at the end of EVERY `flush()`
and `shutdown()`, on the calling thread, after that call's export and drop
accounting completed. A raising listener is logged at ERROR and does not fail the
flush. A writer that records nothing stores the listener and never calls it.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `listener` | `Callable[[MonitoringExportHealth], None] \| None` | — | — |

#### disable

`tai42_contract.monitoring.writer.MonitoringWriter.disable`

```python theme={null}
disable(self) -> AbstractContextManager[None]
```

Suppress emission within the block.

Every recording method honors it. A backend that never emits may no-op it; an
emitting backend may not.

#### flush

`tai42_contract.monitoring.writer.MonitoringWriter.flush`

```python theme={null}
flush(self) -> None
```

Deliver (or count as failed) every ended record, then call the health listener.

#### shutdown

`tai42_contract.monitoring.writer.MonitoringWriter.shutdown`

```python theme={null}
shutdown(self) -> None
```

Tear the exporter down so the next use rebuilds clean (fork-safety), then call the health listener.

Must fully evict the underlying pipeline, not merely flush — a forked child
inherits dead background threads otherwise.

## attribute\_run

`tai42_contract.monitoring.writer.attribute_run`

```python theme={null}
attribute_run(writer: MonitoringWriter, attribution: RunAttribution) -> AbstractContextManager[None]
```

Return the context manager that stamps `attribution` on the ambient trace for the WRAPPED block.

A free function composing `writer` over `MonitoringWriter.trace_attributes`,
kept off the Protocol so structural writers conform without inheriting it. The
caller ENTERS the returned manager AROUND the whole run so the run's spans are
created INSIDE the attribution scope. It RETURNS the manager rather than
entering it — a one-shot enter/exit here would tear the scope down before any
span exists and silently no-op the stamp.

It does NOT gate on `MonitoringWriter.current_trace_id`. A stamp deposited
BEFORE any trace is open is NOT lost: `trace_attributes` is context-scoped — a
conforming backend writes the attributes into the ambient context and lifts them
onto the trace ROOT when a span is subsequently opened inside the scope.
Short-circuiting to a `nullcontext` when `current_trace_id()` is `None`
therefore DROPS the attribution on the common case — a door that deposits then
opens the run's first span — so there is no such guard. This helper is NOT itself
fail-safe against a non-conforming writer: it
CALLS `trace_attributes` here, so a writer whose signature omits these keywords
raises a `TypeError` at THIS call — before any enter/exit guard inside the writer
could run — and a writer that raises on enter/exit surfaces likewise. A caller that
must not be broken by a monitoring-writer fault guards entering the returned manager
(the skeleton run seams do, logging the fault and continuing the run unattributed).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `writer` | `MonitoringWriter` | — | — |
| `attribution` | `RunAttribution` | — | — |


# Plugins (tai42_contract.plugins)
Source: https://docs.tai42.ai/reference/python-sdk/contract-plugins

The PluginSpec model behind tai-plugin.yml.

Plugin manifest contract: the `tai-plugin.yml` schema (`PluginSpec`).

Every installable TAI plugin ships a `tai-plugin.yml` — at its repo root and
as package-data inside the built wheel. The file names the listing
(`namespace/name`), the pip distribution that backs it, the tai42-contract
compatibility range, declared capabilities, and the item-level `provides`
index: one entry per tool/agent/extension/... the package registers, because
items are what users search for while the plugin is what gets installed.

The models here are the one schema shared by the marketplace registry's
validator, the skeleton's installer, and each plugin repo's own spec test.
The YAML I/O helpers live above the contract (`tai42_kit.plugins`) — the
contract itself has no YAML dependency.

`KIND_MANIFEST_BINDINGS` is the single source for how each provided item
kind wires into a `Manifest`: which manifest
field an installer patches and with what shape (a config row, a module-list
entry, a single-module slot, a package-name entry, an `mcp` transport entry,
a `connectors` descriptor-list append, or no manifest field at all for the
env-selected `config` kind).

Version strings are validated as PEP 440 (an anchored regex of the spec's
canonical pattern) and `contract` as a PEP 440 specifier set — shape-level
parseability only; evaluating whether a version satisfies a range is the
consumer's concern.

`display_name` and `icon` are the optional marketplace display metadata: a
human UI title (the UI titleizes `name` when absent) and either a packaged
image path relative to the package root or an `https` URL (the UI falls back
to a generated monogram when absent).

## DATA\_BLOCK\_BY\_KIND

`tai42_contract.plugins.bindings.DATA_BLOCK_BY_KIND`

```python theme={null}
DATA_BLOCK_BY_KIND: Mapping[PluginItemKind, str] = MappingProxyType({PluginItemKind.MCP_SERVER: 'mcp', PluginItemKind.CONNECTOR: 'provider'})
```

## KIND\_MANIFEST\_BINDINGS

`tai42_contract.plugins.bindings.KIND_MANIFEST_BINDINGS`

```python theme={null}
KIND_MANIFEST_BINDINGS: Mapping[PluginItemKind, ManifestBinding] = MappingProxyType({PluginItemKind.TOOL: ManifestBinding(field='tools', mode='config_row', payload='module'), PluginItemKind.AGENT: ManifestBinding(field='agents', mode='config_row', payload='module'), PluginItemKind.EXTENSION: ManifestBinding(field='extensions_modules', mode='module_list', payload='module'), PluginItemKind.CONNECTOR: ManifestBinding(field='connectors', mode='descriptor_entry', payload='data'), PluginItemKind.CHANNEL: ManifestBinding(field='channel_modules', mode='module_list', payload='module'), PluginItemKind.BACKEND: ManifestBinding(field='backend_module', mode='scalar_module', payload='module'), PluginItemKind.STORAGE: ManifestBinding(field='storage_module', mode='scalar_module', payload='module'), PluginItemKind.MONITORING: ManifestBinding(field='monitoring_module', mode='scalar_module', payload='module'), PluginItemKind.WEBHOOK_VERIFIER: ManifestBinding(field='webhook_verifier_modules', mode='module_list', payload='module'), PluginItemKind.CONFIG: ManifestBinding(field=None, mode='env_selected', payload='module'), PluginItemKind.IDENTITY: ManifestBinding(field='lifecycle_modules', mode='module_list', payload='module'), PluginItemKind.STUDIO_PLUGIN: ManifestBinding(field='studio_plugins', mode='package_list', payload='module'), PluginItemKind.ROUTER: ManifestBinding(field='routers_modules', mode='module_list', payload='module'), PluginItemKind.MIDDLEWARE: ManifestBinding(field='middlewares_modules', mode='module_list', payload='module'), PluginItemKind.MCP_SERVER: ManifestBinding(field='mcp', mode='mcp_entry', payload='data'), PluginItemKind.SANDBOX: ManifestBinding(field='sandbox_module', mode='scalar_module', payload='module')})
```

## ManifestBinding

`tai42_contract.plugins.bindings.ManifestBinding`

```python theme={null}
class ManifestBinding(BaseModel)
```

How one provided item kind wires into a `Manifest`.

`field` names the manifest field an installer patches for an item of
this kind; `mode` is the patch shape; `payload` is the axis the item
carries — `module` (the item names an import path) or `data` (the item
carries its kind's declarative block):

* `config_row` — append a config row (`tools`/`agents`) whose
  `module` is the item's module.
* `module_list` — append the item's module to a plain module list.
* `scalar_module` — set a single-module slot; the slot holds ONE module,
  so a second plugin claiming an occupied slot is a conflict the caller
  must reject loudly.
* `package_list` — append the plugin's DISTRIBUTION name (not the item's
  module) to a package list (`studio_plugins`).
* `mcp_entry` — append one `{title: item.name, config: item.mcp}` object
  to the manifest `mcp` list; uninstall removes the entry by title.
* `descriptor_entry` — append the item's `provider` descriptor to the
  manifest `connectors` list; uninstall removes by `provider.id`.
* `env_selected` — no manifest field: the kind is selected through the
  environment (a `config` provider is named by `TAI_CONFIG_MODE` and
  imported by the config seam), so `field` is `None`.

The data modes (`mcp_entry`, `descriptor_entry`) carry `payload ==
"data"`; every other mode carries `payload == "module"`.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `field` | `str \| None` |
| `mode` | `Literal['config_row', 'module_list', 'scalar_module', 'package_list', 'mcp_entry', 'descriptor_entry', 'env_selected']` |
| `payload` | `Literal['module', 'data']` |

## PluginDelivery

`tai42_contract.plugins.spec.PluginDelivery`

```python theme={null}
PluginDelivery = Literal['package', 'descriptor']
```

## PluginItem

`tai42_contract.plugins.item.PluginItem`

```python theme={null}
class PluginItem(BaseModel)
```

One installable item in a plugin's `provides` index.

`module` is the import path whose import side-effect registers the item
(or, for env-selected kinds, the module the selecting seam imports); the
installer patches it into the manifest per `KIND_MANIFEST_BINDINGS`.

The item shape is table-driven on `KIND_MANIFEST_BINDINGS` (a model
validator enforces it, loud both ways): a data-payload kind carries exactly
the declarative block `DATA_BLOCK_BY_KIND` names for it — `mcp`
transport config for `mcp-server`, a `provider` descriptor for
`connector` — and no `module`; every module-payload kind carries
`module` and no data block. A `connector` item's `name` MUST equal its
`provider.id` — that id is the manifest/uninstall key.

`routes` declares the item's HTTP mount: REQUIRED for `kind: router`,
OPTIONAL for `kind: channel`, and FORBIDDEN (must be absent) for every
other kind.

`group` is an OPTIONAL logical family label the author may put on any item
of any kind: items sharing a value belong to one family, and a consumer may
summarize the `provides` index by group. It is purely a structural
self-description of the plugin — cross-kind groups and single-member groups
are both legal, and absent means the item stands alone. It carries a tag's
charset discipline.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `kind` | `PluginItemKind` |
| `name` | `str` |
| `module` | `str \| None` |
| `mcp` | `MCPConfig \| None` |
| `provider` | `ProviderDescriptor \| None` |
| `description` | `str` |
| `tags` | `list[str]` |
| `group` | `str \| None` |
| `routes` | `RoutesDecl \| None` |

## PluginItemKind

`tai42_contract.plugins.bindings.PluginItemKind`

```python theme={null}
class PluginItemKind(StrEnum)
```

Kind of one installable item a plugin provides.

The values are the ecosystem's item-kind vocabulary (the same words the
catalog and the marketplace facets use). `KIND_MANIFEST_BINDINGS` maps
every member onto its manifest wiring; an unknown kind in a spec is a
loud validation reject, never a skipped row.

**Attributes**

| Attribute | Type |
| - | - |
| `TOOL` | — |
| `AGENT` | — |
| `EXTENSION` | — |
| `CONNECTOR` | — |
| `CHANNEL` | — |
| `BACKEND` | — |
| `STORAGE` | — |
| `MONITORING` | — |
| `WEBHOOK_VERIFIER` | — |
| `CONFIG` | — |
| `IDENTITY` | — |
| `STUDIO_PLUGIN` | — |
| `ROUTER` | — |
| `MIDDLEWARE` | — |
| `MCP_SERVER` | — |
| `SANDBOX` | — |

## PluginPermissions

`tai42_contract.plugins.spec.PluginPermissions`

```python theme={null}
class PluginPermissions(BaseModel)
```

Capabilities a plugin declares — informational: surfaced in listings, not enforced by a sandbox.

Omitting the block declares none (every flag defaults to `False`); an
unknown key is rejected loudly rather than silently ignored.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `network` | `bool` |
| `subprocess` | `bool` |
| `filesystem` | `bool` |

## PluginSpec

`tai42_contract.plugins.spec.PluginSpec`

```python theme={null}
class PluginSpec(BaseModel)
```

The complete, validated content of one `tai-plugin.yml`.

Frozen and `extra="forbid"`: a typo'd key fails validation loudly. The
listing reference is `namespace/name` (`ref`); `package` is the
normalized pip distribution the listing points at, OPTIONAL because a spec
whose every item is a data item (`mcp-server`/`connector`) may ship no
package — a *descriptor-only* plugin that installs nothing but its manifest
entry. `delivery` derives the one word every surface shows
(`"package"` when `package` is set, `"descriptor"` when absent); a
spec with any module item MUST name a package. `version` must equal the
built wheel's version (each plugin repo's spec test and the registry's
ingest validation both pin that); `contract` is the tai42-contract
compatibility range as a PEP 440 specifier set, required unless every
provided item is kind `mcp-server` (such a package imports no contract),
and a spec may not mix `mcp-server` with any other kind. A connector
item's `provider.origin` is `system` iff the listing namespace is
`tai42` — a community listing may not claim the system label.
`display_name` and `icon` are optional marketplace display metadata;
`premium` marks a paid listing.

`migrations` is an OPT-IN, package-relative directory holding the plugin's
ordered SQL schema chain — absent means the plugin owns no tables and is not
a migrations plugin (most plugins); it requires a `package`. The contract
validates only the path's SHAPE; the directory's existence in the installed
package is enforced at runner-discovery time, not here.

`migrations_component` optionally names the database component the chain
migrates, for a plugin whose feature store is a SEPARATE, off-unless-declared
component rather than the distribution itself — absent (the default) runs the
chain under the distribution name, byte-identical to prior behavior. Setting
it REQUIRES `migrations` (a component with no chain migrates nothing).

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `spec_version` | `Literal[1]` |
| `namespace` | `str` |
| `name` | `str` |
| `display_name` | `str \| None` |
| `package` | `str \| None` |
| `version` | `str` |
| `description` | `str` |
| `icon` | `str \| None` |
| `premium` | `bool` |
| `license` | `str` |
| `homepage` | `str \| None` |
| `repository` | `str \| None` |
| `contract` | `str \| None` |
| `categories` | `list[str]` |
| `tags` | `list[str]` |
| `permissions` | `PluginPermissions` |
| `provides` | `list[PluginItem]` |
| `migrations` | `str \| None` |
| `migrations_component` | `str \| None` |

### Members

#### ref

`tai42_contract.plugins.spec.PluginSpec.ref`

```python theme={null}
ref: str
```

The full listing reference, `namespace/name`.

#### delivery

`tai42_contract.plugins.spec.PluginSpec.delivery`

```python theme={null}
delivery: PluginDelivery
```

How the plugin is delivered: `"descriptor"` when it ships no package, else `"package"`.

A descriptor is an all-data, install-nothing listing.

## RouteDecl

`tai42_contract.plugins.routes.RouteDecl`

```python theme={null}
class RouteDecl(BaseModel)
```

One HTTP route a plugin item declares, relative to its mount base.

`path` is `/`-prefixed with at least one segment; each segment is a
literal (`ROUTE_LITERAL_SEGMENT_RE`) or a `{name}` template
(`ROUTE_PARAM_SEGMENT_RE`, a python identifier with no converter
suffix). `methods` is a non-empty set of uppercase HTTP methods, unique
within the row. `public` states — with no default, so the declaration is
never silent — whether the resolved route answers unauthenticated.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `path` | `str` |
| `methods` | `list[RouteMethod]` |
| `public` | `bool` |

## RouteMethod

`tai42_contract.plugins.routes.RouteMethod`

```python theme={null}
RouteMethod = Literal['GET', 'POST', 'PUT', 'PATCH', 'DELETE']
```

## RoutesDecl

`tai42_contract.plugins.routes.RoutesDecl`

```python theme={null}
class RoutesDecl(BaseModel)
```

The route block one item declares: a default mount `base` and its rows.

`base` is RELATIVE — one or more `ROUTE_BASE_SEGMENT_RE` segments
joined by `/`, no leading/trailing slash, no templates. The resolved
absolute path of each row is `/api/` + `base` + the row's `path`; the
`/api/` root is fixed platform-wide and only `base` is remappable.
`paths` is non-empty.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `base` | `str` |
| `paths` | `list[RouteDecl]` |

## data\_kinds

`tai42_contract.plugins.bindings.data_kinds`

```python theme={null}
data_kinds() -> frozenset[PluginItemKind]
```

The item kinds whose binding carries `payload == "data"`.

These are the kinds a declarative (no-`module`) item is built for. Derived
from `KIND_MANIFEST_BINDINGS` so the payload table stays the one source.


# Presets (tai42_contract.presets)
Source: https://docs.tai42.ai/reference/python-sdk/contract-presets

The PresetStore protocol and preset document models.

The presets contract: the `PresetSpec` model, `PresetBody` shape, errors, and store.

Covers the `PresetSpec` data model, the
`PresetBody` persisted shape, the preset-specific errors, and the
`PresetStore` Protocol.

A *preset* is a base tool with a partial set of keyword arguments baked in,
exposed as a new named, versioned tool. It is the FIRST typed VIEW over the
generic versioned-document store (`kind="preset"`): the store holds the opaque
body, this Protocol is the typed interface over it. tai42-contract owns only the
Protocol + models + errors; the concrete view that delegates to the store,
validates/reshapes the body, and maps the generic errors to these preset errors
lives in the skeleton (no versioning code in the view).

## CARRY\_FORWARD

`tai42_contract.presets.models.CARRY_FORWARD`

```python theme={null}
CARRY_FORWARD = CarryForward()
```

## CarryForward

`tai42_contract.presets.models.CarryForward`

```python theme={null}
class CarryForward
```

Sentinel for a `save_version` field the caller did not provide.

Carry the ACTIVE value forward. `fixed_kwargs` / `extensions` clear with an empty container, so
`None` is their carry-forward sentinel; `output_schema` / `input_schema`
have no empty container (their cleared state IS `None`), so each needs a
distinct sentinel to tell "not provided" (carry forward) apart from an explicit
`None` (clear).

## PresetBody

`tai42_contract.presets.models.PresetBody`

```python theme={null}
class PresetBody(BaseModel)
```

The persisted body of a versioned preset.

`base_tool` is the tool the preset binds; `description` is the preset's
human description; `fixed_kwargs` are the baked kwargs (each becomes a
hidden, fixed constant on the bound tool). `extensions` is a list of
extension COMBOS — the SAME shape as a manifest `extensions` map value,
each combo element an extension name or a `{"name", "config"}` mapping
binding author config (e.g. an `ask_external` verifier) — fed unconverted
to the structured runtime-attach API at register (an empty outer list means
no extensions; an empty INNER combo is rejected by the validating view).
`output_schema` is an optional author-set OUTPUT JSON Schema (an object
schema): on an AGENT base it is baked into the run tool's `response_format`
so the agent FORCES a structured output matching it; on a plain tool it is
advertised as the bound tool's output schema and every result is validated
against it at run time — a park is a suspend signal, not a result, and passes.
`input_schema` is an optional author-set INPUT JSON
Schema: it becomes the exposed named tool's input contract, and the caller's
validated object is routed into the base tool's declared payload argument (see
`PresetInputSchemaSupport`). Only a base tool that DECLARES input-schema
support accepts one; otherwise a set `input_schema` is a loud authoring error.

Each schema is the `TemplatedText | dict` union: an inline `dict` is the JSON
Schema document itself; a `TemplatedText` names a stored
schema by `id` (or carries it inline as `content`), rendered and parsed as JSON to the
same schema at the point of use and save.

Every field must survive carry-forward on a version save: dropping
`extensions` would make the branch tools vanish on reload, dropping
`base_tool` would break the bind, dropping `description` would strip the
tool's description, dropping `output_schema` would silently un-enforce the
structured output, and dropping `input_schema` would silently un-enforce the
structured input.

A `fixed_kwargs` scalar-string value written `!ENV ${VAR}` is a SECRET
REFERENCE, not a credential: the server resolves it from the environment at bind
and the store keeps only the reference — never the resolved value.

**Attributes**

| Attribute | Type |
| - | - |
| `base_tool` | `str` |
| `description` | `str` |
| `fixed_kwargs` | `dict[str, Any]` |
| `extensions` | `list[list[ExtensionElement]]` |
| `output_schema` | `TemplatedText \| dict[str, Any] \| None` |
| `input_schema` | `TemplatedText \| dict[str, Any] \| None` |
| `state_binding` | `StateBinding \| None` |

## PresetError

`tai42_contract.presets.errors.PresetError`

```python theme={null}
class PresetError(Exception)
```

Base for preset view failures, carrying the preset `name`.

**Attributes**

| Attribute | Type |
| - | - |
| `name` | — |

## PresetExistsError

`tai42_contract.presets.errors.PresetExistsError`

```python theme={null}
class PresetExistsError(PresetError)
```

A preset named `name` already exists.

## PresetInputSchemaSupport

`tai42_contract.presets.models.PresetInputSchemaSupport`

```python theme={null}
class PresetInputSchemaSupport(BaseModel)
```

A base tool's declaration that it ACCEPTS a per-preset input schema.

Most base tools declare none — their typed schema is fixed. A base tool that
declares support names, via `payload_arg`, the base tool's OWN argument the
validated structured input is delivered under: a preset's `input_schema`
becomes the exposed named tool's input contract and the caller's validated
object is routed into `payload_arg` on the base call.

**Attributes**

| Attribute | Type |
| - | - |
| `payload_arg` | `str` |

## PresetNameConflictError

`tai42_contract.presets.errors.PresetNameConflictError`

```python theme={null}
class PresetNameConflictError(PresetError)
```

The preset `name` collides with an existing base tool.

A preset must never silently shadow a real tool, so the register/create path
raises this loudly rather than overwriting the tool.

## PresetNotFoundError

`tai42_contract.presets.errors.PresetNotFoundError`

```python theme={null}
class PresetNotFoundError(PresetError)
```

No preset (or no active preset) named `name`.

## PresetSeed

`tai42_contract.presets.models.PresetSeed`

```python theme={null}
class PresetSeed(BaseModel)
```

A declared default preset a plugin ships for import-time seeding.

A seed names the preset (`name`), its human `description`, the
`base_tool` it binds, and the `fixed_kwargs` baked in — the same body a
`PresetBody` carries — plus the optional author `input_schema` /
`output_schema` and optional `tool_meta` display seed. The applier creates
or upgrades the preset from this shape; the contract holds only the SHAPE,
never the applier logic.

A `fixed_kwargs` scalar-string value written `!ENV ${VAR}` is a SECRET
REFERENCE, not a credential: the server resolves it from the environment at bind
and the store keeps only the reference — never the resolved value.

**Attributes**

| Attribute | Type |
| - | - |
| `name` | `str` |
| `description` | `str` |
| `base_tool` | `str` |
| `fixed_kwargs` | `dict[str, Any]` |
| `input_schema` | `TemplatedText \| dict[str, Any] \| None` |
| `output_schema` | `TemplatedText \| dict[str, Any] \| None` |
| `tool_meta` | `PresetSeedToolMeta \| None` |
| `state_binding` | `StateBinding \| None` |

## PresetSeedToolMeta

`tai42_contract.presets.models.PresetSeedToolMeta`

```python theme={null}
class PresetSeedToolMeta(BaseModel)
```

The optional display metadata a `PresetSeed` seeds onto its preset's tool\_meta.

Each field is applied only where the preset's tool\_meta leaves it absent — a seed never overwrites
an operator-set display value.

`display_name` is the human tool title; `tags` label it in listings;
`folder_path` is a `/`-style path the applier resolves into the tool\_meta
folder tree (creating missing segments), never a raw stored string.

**Attributes**

| Attribute | Type |
| - | - |
| `display_name` | `str \| None` |
| `tags` | `list[str] \| None` |
| `folder_path` | `str \| None` |

## PresetSpec

`tai42_contract.agent.base.PresetSpec`

```python theme={null}
class PresetSpec(BaseModel)
```

A base tool bound to fixed kwargs, bound as one more tool of the run that carries it.

`name` follows `PRESET_NAME_PATTERN`. A base tool that interprets its fixed kwargs as a
nested document carries that document opaquely here.

**Attributes**

| Attribute | Type |
| - | - |
| `name` | `str` |
| `description` | `str` |
| `base_tool` | `str` |
| `fixed_kwargs` | `dict[str, Any]` |

## PresetStore

`tai42_contract.presets.PresetStore`

```python theme={null}
class PresetStore(Protocol)
```

The typed interface over the versioned-document store with `kind="preset"`.

Delegation, body validation/reshaping, and error mapping are the concrete
(skeleton) view's job — this Protocol pins only the surface. A preset body is
always the full `PresetBody` (`{base_tool, description, fixed_kwargs,
extensions}`); the editable-field methods reconstruct it under the
carry-forward rules documented on `save_version`.

### Members

#### create\_preset

`tai42_contract.presets.PresetStore.create_preset`

```python theme={null}
async create_preset(
    self,
    spec: PresetSpec,
    extensions: Sequence[Sequence[ExtensionElement]],
    output_schema: TemplatedText | dict[str, Any] | None = None,
    input_schema: TemplatedText | dict[str, Any] | None = None,
    *,
    state_binding: StateBinding | None = None,
    tags: list[str] | None = None,
) -> DocumentRecord
```

Create a versioned preset.

`spec` carries `name`/`description`/
`base_tool`/`fixed_kwargs`; `extensions` (the combos list) and the
optional `output_schema` / `input_schema` ride alongside — all of them
land in the persisted `PresetBody`. `tags` labels version 1 in the
SAME create commit (`None` leaves it untagged); a caller that must tag the
first version does so atomically, never through a separate follow-up write.
Raise `ValueError` on a blank `description`,
`PresetExistsError` on a duplicate name,
`PresetNameConflictError` if the name collides with a base tool.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `spec` | `PresetSpec` | — | — |
| `extensions` | `Sequence[Sequence[ExtensionElement]]` | — | — |
| `output_schema` | `TemplatedText \| dict[str, Any] \| None` | `None` | — |
| `input_schema` | `TemplatedText \| dict[str, Any] \| None` | `None` | — |
| `state_binding` | `StateBinding \| None` | `None` | — |
| `tags` | `list[str] \| None` | `None` | — |

#### save\_version

`tai42_contract.presets.PresetStore.save_version`

```python theme={null}
async save_version(
    self,
    name: str,
    fixed_kwargs: dict[str, Any] | None = None,
    extensions: Sequence[Sequence[ExtensionElement]] | None = None,
    output_schema: TemplatedText | dict[str, Any] | CarryForward | None = CARRY_FORWARD,
    description: str | None = None,
    *,
    input_schema: TemplatedText | dict[str, Any] | CarryForward | None = CARRY_FORWARD,
    state_binding: StateBinding | CarryForward | None = CARRY_FORWARD,
    tags: list[str] | None = None,
) -> DocumentVersion
```

Append a new version from the editable body fields.

`tags` labels the new version in the SAME save commit (`None` leaves it
untagged, the door's default); a caller that must tag the version does so
atomically, never through a separate follow-up write.

A version body is the FULL `PresetBody`, so the view reconstructs
the new body by ALWAYS carrying `base_tool` forward from the ACTIVE
version body, then applying each of `fixed_kwargs`, `extensions` under
one UNIFORM sentinel: omitted/`None` = carry the active value forward
unchanged; an explicit empty list (`extensions=[]`) = deliberately CLEAR
that field. An explicitly provided empty list is a value, never "not
provided". `output_schema` and `input_schema` each follow the SAME rule
but with a distinct `CARRY_FORWARD` sentinel (their cleared state is
`None`, so `None` cannot double as "not provided"): omitted = carry
forward, an explicit `None` = clear, an explicit dict = wins.
`description` is editable per
version: `None` = carry the active description forward, an explicit
non-empty string = set it. The RESULTING description — explicit or carried
— is validated non-empty (raising `ValueError`, surfaced as a 400),
so an explicit `""` is rejected. An empty INNER combo
(`[[]]` or any `[]` member of `extensions`) is REJECTED. The new body
never DROPS a field. Raise `PresetNotFoundError` if the preset is
absent.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `fixed_kwargs` | `dict[str, Any] \| None` | `None` | — |
| `extensions` | `Sequence[Sequence[ExtensionElement]] \| None` | `None` | — |
| `output_schema` | `TemplatedText \| dict[str, Any] \| CarryForward \| None` | `CARRY_FORWARD` | — |
| `description` | `str \| None` | `None` | — |
| `input_schema` | `TemplatedText \| dict[str, Any] \| CarryForward \| None` | `CARRY_FORWARD` | — |
| `state_binding` | `StateBinding \| CarryForward \| None` | `CARRY_FORWARD` | — |
| `tags` | `list[str] \| None` | `None` | — |

#### list\_presets

`tai42_contract.presets.PresetStore.list_presets`

```python theme={null}
async list_presets(self) -> list[DocumentRecord]
```

List the active versioned presets.

#### get\_preset

`tai42_contract.presets.PresetStore.get_preset`

```python theme={null}
async get_preset(self, name: str) -> DocumentRecord
```

Fetch a preset's active record.

Raise `PresetNotFoundError` if absent.

**Parameters**

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

#### get\_active\_kwargs

`tai42_contract.presets.PresetStore.get_active_kwargs`

```python theme={null}
async get_active_kwargs(self, name: str) -> dict[str, Any]
```

Return the active version's baked `fixed_kwargs`.

Raise `PresetNotFoundError` if absent.

**Parameters**

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

#### list\_versions

`tai42_contract.presets.PresetStore.list_versions`

```python theme={null}
async list_versions(self, name: str) -> list[DocumentVersion]
```

List every version of the preset, each carrying its `is_current` signal.

Raise `PresetNotFoundError` if the preset is absent.

**Parameters**

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

#### get\_version

`tai42_contract.presets.PresetStore.get_version`

```python theme={null}
async get_version(self, name: str, version: int) -> DocumentVersion
```

Fetch one version.

Raise `PresetVersionNotFoundError` if that version does not exist.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `version` | `int` | — | — |

#### get\_active\_body

`tai42_contract.presets.PresetStore.get_active_body`

```python theme={null}
async get_active_body(self, name: str) -> PresetBody
```

Return the FULL active-version body (`{base_tool, description, fixed_kwargs, extensions}`).

So reload/startup can re-register from the whole body, not just
`fixed_kwargs`. Raise `PresetNotFoundError` if absent.

**Parameters**

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

#### rollback

`tai42_contract.presets.PresetStore.rollback`

```python theme={null}
async rollback(self, name: str, version: int) -> DocumentRecord
```

Re-point the active version to `version` (no data copy).

Raise `PresetVersionNotFoundError` if that version does not exist.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `version` | `int` | — | — |

#### soft\_delete

`tai42_contract.presets.PresetStore.soft_delete`

```python theme={null}
async soft_delete(self, name: str) -> None
```

Soft-delete the preset, keeping its version history (audit).

Raise `PresetNotFoundError` if absent.

**Parameters**

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

#### rename\_preset

`tai42_contract.presets.PresetStore.rename_preset`

```python theme={null}
async rename_preset(self, name: str, new_name: str) -> DocumentRecord
```

Re-key a preset from `name` to `new_name`.

Delegates to the generic store's rename under
`kind="preset"`. The version history, every per-version
`tags` label, and the `active_version` pointer are preserved by the store
contract — a rename moves a key, it never rewrites the body. Raise
`PresetNotFoundError` for an absent `name`, `PresetExistsError`
when `new_name` is already a live preset, and `PresetNameConflictError`
when the injected collision predicate says `new_name` is held by a live
non-preset tool (the same predicate `create_preset` consults).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `new_name` | `str` | — | — |

## PresetVersionNotFoundError

`tai42_contract.presets.errors.PresetVersionNotFoundError`

```python theme={null}
class PresetVersionNotFoundError(PresetError)
```

No version `version` exists for preset `name`.

**Attributes**

| Attribute | Type |
| - | - |
| `version` | — |

## PresetWriteValidator

`tai42_contract.presets.PresetWriteValidator`

```python theme={null}
PresetWriteValidator = Callable[[PresetBody], Awaitable[Sequence[str]]]
```


# Sandbox (tai42_contract.sandbox)
Source: https://docs.tai42.ai/reference/python-sdk/contract-sandbox

The Sandbox ABC a sandbox provider implements, plus its session, spec, and policy models.

Sandbox contract.

Exposes the neutral session models, the resolved `SandboxPolicy`, the error family, and
the `Sandbox` / `SandboxSession` / `SandboxExecHandle` ABCs.

WHAT THE CONTRACT CARRIES: the shape of a session request/result, the security
policy the kit enforces, the failure family, and the provider face — no logic.
WHAT THE KIT OWNS: the shared session ledger, TTL/reap bookkeeping, and the
session-create policy chokepoint (a `Sandbox` / `SandboxSession` base a
provider extends). WHAT A PROVIDER IMPLEMENTS: only its runtime I/O — creating
session resources and running `exec` / file transfers against them.

## ExecResult

`tai42_contract.sandbox.models.ExecResult`

```python theme={null}
class ExecResult(BaseModel)
```

The outcome of a completed non-interactive `exec`.

**Attributes**

| Attribute | Type |
| - | - |
| `exit_code` | `int` |
| `stdout` | `str` |
| `stderr` | `str` |

## Sandbox

`tai42_contract.sandbox.base.Sandbox`

```python theme={null}
class Sandbox(ABC)
```

Abstract sandbox provider for a Tai app.

A provider creates/destroys disposable `SandboxSession` instances and
reaps expired ones. The app core depends only on this interface and stays
sandbox-agnostic; concrete providers (a container runtime, a direct-host
runner) implement it and register via
`@tai42_app.sandboxes.register_sandbox`.

### Members

#### create\_session

`tai42_contract.sandbox.base.Sandbox.create_session`

```python theme={null}
async create_session(self, spec: SandboxSessionSpec) -> SandboxSession
```

Create a session from `spec` or REJECT it with `SandboxSpecRejectedError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `spec` | `SandboxSessionSpec` | — | — |

#### get\_session

`tai42_contract.sandbox.base.Sandbox.get_session`

```python theme={null}
async get_session(self, session_id: str) -> SandboxSession
```

Fetch a live session by id.

Raise `SandboxSessionNotFoundError` if absent.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `session_id` | `str` | — | — |

#### list\_sessions

`tai42_contract.sandbox.base.Sandbox.list_sessions`

```python theme={null}
async list_sessions(self) -> list[SandboxSessionInfo]
```

The observable state of every live session.

#### destroy\_session

`tai42_contract.sandbox.base.Sandbox.destroy_session`

```python theme={null}
async destroy_session(self, session_id: str) -> None
```

Tear a session down. Idempotent on an already-gone session.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `session_id` | `str` | — | — |

#### reap

`tai42_contract.sandbox.base.Sandbox.reap`

```python theme={null}
async reap(self) -> list[str]
```

Destroy every session past its `expires_at` and return the destroyed ids.

#### exec\_default\_timeout\_seconds

`tai42_contract.sandbox.base.Sandbox.exec_default_timeout_seconds`

```python theme={null}
exec_default_timeout_seconds: float
```

The provider's configured default for one short exec; `exec` itself still requires `timeout_seconds`.

#### reap\_interval\_seconds

`tai42_contract.sandbox.base.Sandbox.reap_interval_seconds`

```python theme={null}
reap_interval_seconds: float
```

The provider's configured reap sweep cadence.

## SandboxDurability

`tai42_contract.sandbox.models.SandboxDurability`

```python theme={null}
SandboxDurability = Literal['ephemeral', 'persistent']
```

## SandboxError

`tai42_contract.sandbox.errors.SandboxError`

```python theme={null}
class SandboxError(Exception)
```

Base for every sandbox failure.

## SandboxExecHandle

`tai42_contract.sandbox.base.SandboxExecHandle`

```python theme={null}
class SandboxExecHandle(ABC)
```

A live interactive exec started by `SandboxSession.exec_start`.

CONCURRENCY CONTRACT: `write_stdin` / `close_stdin` MUST be safe
to call concurrently with active `output` iteration — a provider that
serializes reads and writes on one attach stream does its OWN demux/buffering
(a deadlocking handle is non-conformant). A single `write_stdin` call
delivers its bytes intact and in order (the provider must not split or reorder
them); a consumer multiplexing a line protocol holds its OWN single-writer
lock so each message is one atomic call — the provider does no framing.

LIFETIME CONTRACT: after the exec has exited, `kill` is idempotent (a
safe no-op) and `write_stdin` raises a typed `SandboxError`
(never an arbitrary exception).

### Members

#### write\_stdin

`tai42_contract.sandbox.base.SandboxExecHandle.write_stdin`

```python theme={null}
async write_stdin(self, data: bytes) -> None
```

Deliver `data` to the exec's stdin intact and in order.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `data` | `bytes` | — | — |

#### close\_stdin

`tai42_contract.sandbox.base.SandboxExecHandle.close_stdin`

```python theme={null}
async close_stdin(self) -> None
```

Signal end-of-input to the exec.

#### output

`tai42_contract.sandbox.base.SandboxExecHandle.output`

```python theme={null}
output: AsyncIterator[SandboxStreamChunk | SandboxStreamExit]
```

The interleaved stdout/stderr stream, terminated by one `SandboxStreamExit`.

On `timeout_seconds` expiry the provider kills the exec and the iterator raises
`SandboxExecTimeoutError`.

#### kill

`tai42_contract.sandbox.base.SandboxExecHandle.kill`

```python theme={null}
async kill(self) -> None
```

Terminate the exec. Idempotent once the exec has exited.

## SandboxExecTimeoutError

`tai42_contract.sandbox.errors.SandboxExecTimeoutError`

```python theme={null}
class SandboxExecTimeoutError(SandboxError)
```

An `exec` / `exec_start` exceeded its `timeout_seconds`.

Carries the partial-output LENGTHS (never the content — output may hold
secrets read from `env`) so a caller can log the shape of what was produced
before the kill.

**Attributes**

| Attribute | Type |
| - | - |
| `timeout_seconds` | — |
| `stdout_len` | — |
| `stderr_len` | — |

## SandboxFileNotFoundError

`tai42_contract.sandbox.errors.SandboxFileNotFoundError`

```python theme={null}
class SandboxFileNotFoundError(SandboxError)
```

No file exists at the requested path in the session's workspace.

Raised by a provider's `get_file` ONLY when `path` does not exist in the session's
workspace. Every OTHER read failure (an IO/permission/engine error, an unreadable non-file)
stays the base `SandboxError` carrying the real message, so a caller can tell a genuine
miss (report the file absent) from a real fault (surface the error), never masking one as the
other.

**Attributes**

| Attribute | Type |
| - | - |
| `path` | — |

## SandboxIsolation

`tai42_contract.sandbox.models.SandboxIsolation`

```python theme={null}
SandboxIsolation = Literal['none', 'container', 'vm']
```

## SandboxNetwork

`tai42_contract.sandbox.models.SandboxNetwork`

```python theme={null}
SandboxNetwork = Literal['none', 'internal', 'egress']
```

## SandboxPolicy

`tai42_contract.sandbox.policy.SandboxPolicy`

```python theme={null}
class SandboxPolicy(BaseModel)
```

The resolved security policy the kit enforces at session create.

`egress` is the network CEILING (a session's `network` must be
at-or-tighter); `isolation` is the strength FLOOR (a session runs at
at-least this level); `durable` gates whether a `persistent` session is
permitted at all; `scrub_transcript` is carried for the consumer to read —
it is applied consumer-side, NOT a create-time gate. It is a pure
platform-policy envelope — no consumer concept lives here.

**Attributes**

| Attribute | Type |
| - | - |
| `egress` | `SandboxNetwork` |
| `isolation` | `SandboxIsolation` |
| `scrub_transcript` | `bool` |
| `durable` | `bool` |

## SandboxSession

`tai42_contract.sandbox.base.SandboxSession`

```python theme={null}
class SandboxSession(ABC)
```

One live sandbox session — the unit a consumer runs code in.

### Members

#### id

`tai42_contract.sandbox.base.SandboxSession.id`

```python theme={null}
id: str
```

This session's provider-assigned id.

#### workspace\_path

`tai42_contract.sandbox.base.SandboxSession.workspace_path`

```python theme={null}
workspace_path: str
```

The provider's ABSOLUTE root path for THIS session's workspace.

Also carried on `SandboxSessionInfo` so a caller can read it off
`info()` too. Anchors the workspace-relative resolution of `cwd` /
`path` (see the module path contract).

#### info

`tai42_contract.sandbox.base.SandboxSession.info`

```python theme={null}
async info(self) -> SandboxSessionInfo
```

This session's observable state.

#### exec

`tai42_contract.sandbox.base.SandboxSession.exec`

```python theme={null}
async exec(
    self,
    argv: Sequence[str],
    *,
    cwd: str | None = None,
    env: dict[str, SecretStr] | None = None,
    stdin: bytes | None = None,
    timeout_seconds: float,
) -> ExecResult
```

Run `argv` to completion and return its `ExecResult`.

`timeout_seconds` is REQUIRED: on expiry the provider kills the exec and
raises `SandboxExecTimeoutError`. `env` overlays the session's
base `spec.env` (per-exec keys override on collision). `cwd` is
WORKSPACE-RELATIVE by default (resolved against `workspace_path`; unset
defaults to `workspace_path`) per the module path contract.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `argv` | `Sequence[str]` | — | — |
| `cwd` | `str \| None` | `None` | — |
| `env` | `dict[str, SecretStr] \| None` | `None` | — |
| `stdin` | `bytes \| None` | `None` | — |
| `timeout_seconds` | `float` | — | — |

#### exec\_start

`tai42_contract.sandbox.base.SandboxSession.exec_start`

```python theme={null}
async exec_start(
    self,
    argv: Sequence[str],
    *,
    cwd: str | None = None,
    env: dict[str, SecretStr] | None = None,
    timeout_seconds: float,
) -> SandboxExecHandle
```

Start `argv` as an INTERACTIVE exec, returning a `SandboxExecHandle`.

`timeout_seconds` is REQUIRED: on expiry the provider kills the exec and
the handle's `output` iterator raises `SandboxExecTimeoutError`.
`env` and `cwd` follow the same rules as `exec`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `argv` | `Sequence[str]` | — | — |
| `cwd` | `str \| None` | `None` | — |
| `env` | `dict[str, SecretStr] \| None` | `None` | — |
| `timeout_seconds` | `float` | — | — |

#### put\_file

`tai42_contract.sandbox.base.SandboxSession.put_file`

```python theme={null}
async put_file(self, path: str, data: bytes) -> None
```

Write `data` to `path` (WORKSPACE-RELATIVE by default) in the workspace.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `str` | — | — |
| `data` | `bytes` | — | — |

#### get\_file

`tai42_contract.sandbox.base.SandboxSession.get_file`

```python theme={null}
async get_file(self, path: str) -> bytes
```

Read `path` (WORKSPACE-RELATIVE by default) from the workspace.

Raise `SandboxFileNotFoundError` when `path` does not
exist; any other read failure raises the base `SandboxError` with the real message.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `str` | — | — |

#### touch

`tai42_contract.sandbox.base.SandboxSession.touch`

```python theme={null}
async touch(self) -> None
```

Extend `expires_at` by the session's ttl — a keep-alive turn.

#### destroy

`tai42_contract.sandbox.base.SandboxSession.destroy`

```python theme={null}
async destroy(self) -> None
```

Tear this session down.

## SandboxSessionInfo

`tai42_contract.sandbox.models.SandboxSessionInfo`

```python theme={null}
class SandboxSessionInfo(BaseModel)
```

The observable state of a live session, returned by `info()` / `list_sessions()`.

**Attributes**

| Attribute | Type |
| - | - |
| `id` | `str` |
| `image` | `str` |
| `workspace_key` | `str` |
| `workspace_path` | `str` |
| `durability` | `SandboxDurability` |
| `created_at` | `datetime` |
| `expires_at` | `datetime` |
| `labels` | `dict[str, str]` |

## SandboxSessionNotFoundError

`tai42_contract.sandbox.errors.SandboxSessionNotFoundError`

```python theme={null}
class SandboxSessionNotFoundError(SandboxError)
```

No live session has the requested id.

**Attributes**

| Attribute | Type |
| - | - |
| `session_id` | — |

## SandboxSessionSpec

`tai42_contract.sandbox.models.SandboxSessionSpec`

```python theme={null}
class SandboxSessionSpec(BaseModel)
```

The requested shape of one sandbox session.

The CONSUMER declares the session it needs; the provider maps each field onto
its runtime or REJECTS with `SandboxSpecRejectedError`
what it cannot honor — it never silently downgrades a request.

**Attributes**

| Attribute | Type |
| - | - |
| `image` | `str` |
| `workspace_key` | `str` |
| `durability` | `SandboxDurability` |
| `env` | `dict[str, SecretStr]` |
| `network` | `SandboxNetwork` |
| `isolation` | `SandboxIsolation \| None` |
| `cpu` | `float \| None` |
| `memory_mb` | `int \| None` |
| `ttl_seconds` | `int` |
| `labels` | `dict[str, str]` |

## SandboxSpecRejectedError

`tai42_contract.sandbox.errors.SandboxSpecRejectedError`

```python theme={null}
class SandboxSpecRejectedError(SandboxError)
```

A `SandboxSessionSpec` cannot be honored.

ONE error for two causes the message distinguishes: EITHER the provider
cannot enforce the spec (e.g. `persistent` on a provider without durable
storage, an unenforceable cap) OR the spec violates the operator policy at the
kit session-create chokepoint (a `network` looser than the egress ceiling,
an `isolation` below the floor, `persistent` while durable is off). The
message names which; the family never silently downgrades a rejected spec.

## SandboxStreamChunk

`tai42_contract.sandbox.models.SandboxStreamChunk`

```python theme={null}
class SandboxStreamChunk(BaseModel)
```

One interleaved output frame from an interactive `exec_start`.

**Attributes**

| Attribute | Type |
| - | - |
| `stream` | `Literal['stdout', 'stderr']` |
| `data` | `bytes` |

## SandboxStreamExit

`tai42_contract.sandbox.models.SandboxStreamExit`

```python theme={null}
class SandboxStreamExit(BaseModel)
```

The interactive iterator's final item, carrying the exec's exit code.

**Attributes**

| Attribute | Type |
| - | - |
| `exit_code` | `int` |

## SandboxUnavailableError

`tai42_contract.sandbox.errors.SandboxUnavailableError`

```python theme={null}
class SandboxUnavailableError(SandboxError)
```

No sandbox provider is registered.

Raised by the facet `require_sandbox()` acquisition chokepoint so every
consumer catches this ONE type when no provider backs the seam.

## isolation\_strength

`tai42_contract.sandbox.policy.isolation_strength`

```python theme={null}
isolation_strength(isolation: SandboxIsolation) -> int
```

The strength rank of an isolation tier (`none` \< `container` \< `vm`).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `isolation` | `SandboxIsolation` | — | — |

## network\_openness

`tai42_contract.sandbox.policy.network_openness`

```python theme={null}
network_openness(network: SandboxNetwork) -> int
```

The openness rank of a network tier (`none` \< `internal` \< `egress`).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `network` | `SandboxNetwork` | — | — |


# Storage (tai42_contract.storage)
Source: https://docs.tai42.ai/reference/python-sdk/contract-storage

The Storage protocol a storage provider implements.

The base content-store contract.

`Storage` is "where content is stored" — distinct from
`tai42_contract.template` ("what we do with it", the render mixins). The store
exposes the text surface `load` / `list` / `upload` / `delete` /
`delete_dir` plus the binary/media surface `load_bytes` / `upload_bytes` /
`stat`, with the module-level `assert_not_root` guarding deletes against the
store root. The binary methods ship text-bridging defaults so a text-only backend
satisfies the whole contract with no new code; binary-native backends override.

## ObjectStat

`tai42_contract.storage.ObjectStat`

```python theme={null}
class ObjectStat(BaseModel)
```

Metadata for a stored object, returned by `Storage.stat`.

Carries only `content_type` — the MIME type consumed here for image/audio
media gating (a backend that stores no metadata infers it from the path, a
metadata-bearing backend returns the stored type). Frozen: a stat snapshot is
a value, not a mutable handle.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `content_type` | `str \| None` |

## Storage

`tai42_contract.storage.Storage`

```python theme={null}
class Storage(ABC)
```

The abstract object-store contract: load, list, upload and delete objects by path.

Files and directories share one id space; a backend maps missing objects to
`FileNotFoundError` and colliding paths to `StoragePathConflictError`.

### Members

#### load

`tai42_contract.storage.Storage.load`

```python theme={null}
async load(self, path: str) -> str
```

Return the content at `path`.

Must raise `FileNotFoundError` when the item does not exist — the
manager relies on that exact type to map a missing `{% include %}` /
`{% extends %}` dependency to Jinja's `TemplateNotFound` (so
`{% include ... ignore missing %}` works). Any other failure (auth,
network) must propagate as its own error.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `str` | — | — |

#### list

`tai42_contract.storage.Storage.list`

```python theme={null}
async list(self) -> builtins.list[str]
```

Return every stored object path, in no guaranteed order.

#### upload

`tai42_contract.storage.Storage.upload`

```python theme={null}
async upload(self, path: str, content: str) -> None
```

Store `content` at `path` (create or overwrite).

Files and directories share one id space, so an upload whose `path`
collides with the store's existing shape — an id that still names a
non-empty directory, or an id nested beneath an id already held as a file
— raises `StoragePathConflictError`. An id naming an empty leftover
directory is free to hold a file.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `str` | — | — |
| `content` | `str` | — | — |

#### delete

`tai42_contract.storage.Storage.delete`

```python theme={null}
async delete(self, path: str) -> None
```

Delete the object at `path`, raising `FileNotFoundError` when it does not exist.

A caller wanting idempotent semantics maps that `FileNotFoundError` to a no-op.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `str` | — | — |

#### delete\_dir

`tai42_contract.storage.Storage.delete_dir`

```python theme={null}
async delete_dir(self, path: str) -> None
```

Delete every object under `path`.

Path and existence validation (`ValueError` / `FileNotFoundError`) must complete
before any deletion begins — once destruction starts, failures surface as other
exception types, so callers can treat those two as pre-mutation.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `str` | — | — |

#### load\_bytes

`tai42_contract.storage.Storage.load_bytes`

```python theme={null}
async load_bytes(self, path: str) -> bytes
```

Return the raw bytes at `path`, with the same `FileNotFoundError` contract as `load`.

Text-bridge default: reads the text via `load` and UTF-8 encodes it,
so a text-only backend serves bytes for free. A binary-native backend
(e.g. S3) overrides to return the stored bytes unaltered.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `str` | — | — |

#### upload\_bytes

`tai42_contract.storage.Storage.upload_bytes`

```python theme={null}
async upload_bytes(self, path: str, data: bytes, content_type: str | None = None) -> None
```

Store raw `data` at `path`, optionally tagging `content_type`.

Text-bridge default: STRICT-decodes `data` as UTF-8 and stores it via
`upload`; `content_type` is ignored (a text backend keeps no MIME
metadata). The decode never passes `errors=` — non-UTF-8 bytes raise
`UnicodeDecodeError` loudly rather than corrupting the stored content. A
binary-native backend overrides to store `data` and `content_type` as-is.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `str` | — | — |
| `data` | `bytes` | — | — |
| `content_type` | `str \| None` | `None` | — |

#### stat

`tai42_contract.storage.Storage.stat`

```python theme={null}
async stat(self, path: str) -> ObjectStat
```

Return metadata for the object at `path`.

Path-inference default: guesses `content_type` from the path suffix via
`mimetypes.guess_type` — it does NOT verify existence (it answers from
the path string), so a standalone `stat` on a metadata-less backend is
best-effort metadata; existence for a real read is enforced by the paired
`load_bytes`. A metadata-bearing backend (e.g. S3) overrides to
return the stored content-type and maps a missing object to
`FileNotFoundError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `str` | — | — |

## StoragePathConflictError

`tai42_contract.storage.StoragePathConflictError`

```python theme={null}
class StoragePathConflictError(Exception)
```

An upload id collides with the store's existing shape.

A single id space is shared by files and directories, so one id can name only
one of them: an id that still names a directory holding objects cannot also
become a file, and an object cannot be stored beneath an id already held as a
file. A backend raises this instead of leaking a backend-specific error, so a
surface maps it to a 409 conflict. `path` is the rejected id; `conflicts`
names the stored ids it collides with.

**Attributes**

| Attribute | Type |
| - | - |
| `path` | — |
| `conflicts` | — |

### Members

#### conflicts\_summary

`tai42_contract.storage.StoragePathConflictError.conflicts_summary`

```python theme={null}
conflicts_summary(self) -> str
```

The conflicting ids as a human string, capped at `_MESSAGE_CONFLICT_CAP`.

Beyond the cap a `… and N more` tail is appended; the full list stays on
`conflicts`.

## assert\_not\_root

`tai42_contract.storage.assert_not_root`

```python theme={null}
assert_not_root(path: str) -> None
```

Reject a directory path that resolves to the storage root.

A blank path, one consisting only of slashes and dots (`""`, `"."`,
`"/"`, `"  "`), or one whose normalized form escapes to or above the
root (`"a/.."`, `"./x/../.."`) would target every stored item, so
deleting it is refused. Shared by all storage backends to keep the guard
identical.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `str` | — | — |


# Tools (tai42_contract.tools)
Source: https://docs.tai42.ai/reference/python-sdk/contract-tools

Tool registration types and the app tools namespace.

Tools contract: the `ToolInfo` model + the `AppTools` tool/toolkit registration sub-protocol.

The vendor return type fastmcp `Tool` is `TYPE_CHECKING`-only; an in-process tool is the
framework-neutral `ClientTool` handle.

`AppTools` is the `app.tools` namespace of the assembled facade (`tai42_contract.app`).

## DEFAULT\_RETRYABLE\_KINDS

`tai42_contract.tools.retry.DEFAULT_RETRYABLE_KINDS`

```python theme={null}
DEFAULT_RETRYABLE_KINDS: frozenset[ErrorKind] = frozenset({ErrorKind.TIMED_OUT, ErrorKind.UNAVAILABLE})
```

## MAX\_ATTEMPTS\_CEILING

`tai42_contract.tools.retry.MAX_ATTEMPTS_CEILING`

```python theme={null}
MAX_ATTEMPTS_CEILING = 10
```

## NEVER\_RETRYABLE\_KINDS

`tai42_contract.tools.retry.NEVER_RETRYABLE_KINDS`

```python theme={null}
NEVER_RETRYABLE_KINDS: frozenset[ErrorKind] = frozenset({ErrorKind.UNKNOWN, ErrorKind.CANCELLED})
```

## TOOL\_EXTRA\_IDEMPOTENCY\_KEY

`tai42_contract.tools.meta.TOOL_EXTRA_IDEMPOTENCY_KEY`

```python theme={null}
TOOL_EXTRA_IDEMPOTENCY_KEY: Final = 'tai42/idempotency_key'
```

The extras key under which the platform passes a run's idempotency key: the same value on every
attempt and replay of one logical run, so a tool that declares reading it can make a repeated call a no-op.

## TOOL\_META\_BADGES

`tai42_contract.tools.meta.TOOL_META_BADGES`

```python theme={null}
TOOL_META_BADGES: Final = 'tai42/badges'
```

A list of the tool's own informational capability badges; the tool listing reports them.

## TOOL\_META\_CRASH\_RESUME

`tai42_contract.tools.meta.TOOL_META_CRASH_RESUME`

```python theme={null}
TOOL_META_CRASH_RESUME: Final = 'tai42/crash_resume'
```

Value `True`: a detached recorded run of this tool (a hook or trigger fire, a background submit) found
lost after a worker crash is resumed instead of left lost.

## TOOL\_META\_HIDDEN

`tai42_contract.tools.meta.TOOL_META_HIDDEN`

```python theme={null}
TOOL_META_HIDDEN: Final = 'tai42/hidden'
```

Value `True`: the tool declares itself hidden; the tool listing reports the declaration.

## TOOL\_META\_PAUSES

`tai42_contract.tools.meta.TOOL_META_PAUSES`

```python theme={null}
TOOL_META_PAUSES: Final = 'tai42/pauses'
```

Value `True`: this tool can pause — it can return a park signal (`SuspendedInteraction` or
`ResumeBuffered`) because it parks, asks, or waits on a participant out of band. A tool without it never pauses.

## AppTools

`tai42_contract.tools.AppTools`

```python theme={null}
class AppTools(Protocol)
```

Tool + toolkit registration / lookup surface.

### Members

#### tool\_title

`tai42_contract.tools.AppTools.tool_title`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
async get_tools(self) -> dict[str, Tool]
```

Return every assembled tool keyed by name.

#### get\_client\_tools

`tai42_contract.tools.AppTools.get_client_tools`

```python theme={null}
async get_client_tools(self, names: list[str] | None = None) -> list[ClientTool]
```

The tools named in `names` (all when `None`) as framework-neutral handles; an unknown name raises.

**Parameters**

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

#### run\_tool

`tai42_contract.tools.AppTools.run_tool`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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` | — | — |

#### pauses

`tai42_contract.tools.AppTools.pauses`

```python theme={null}
async pauses(self, key: str) -> bool
```

Whether a dispatch of `key` can return a park signal.

The tool registered under `key` declares `TOOL_META_PAUSES`, or it is an extension
branch whose base declares it or whose extension stack holds an extension registered
with `pauses=True`, or it is a preset (transformed tool) whose `parent_tool` chain
reaches such a tool. An unknown name answers `False` (its own dispatch surfaces the
not-found). A dispatch of a tool that answers `False` and returns a park signal is
refused with `UndeclaredPauseError`.

**Parameters**

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

#### remove\_tool

`tai42_contract.tools.AppTools.remove_tool`

```python theme={null}
remove_tool(self, name: str) -> None
```

Remove the tool registered under `name`.

**Parameters**

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

#### surface\_generation

`tai42_contract.tools.AppTools.surface_generation`

```python theme={null}
surface_generation(self) -> int
```

A number that changes whenever the set of tools this process lists changes.

Monotonic within a process; never compared across processes. A consumer that caches
anything derived from `get_tools`/`get_client_tools` keys the cache on it.

#### register\_tool\_info

`tai42_contract.tools.AppTools.register_tool_info`

```python theme={null}
register_tool_info(self, name: str, combos: Sequence[Sequence[ExtensionElement]] | None = None) -> None
```

Register base tool `name`'s extension combos, attaching each combo stack to the base.

**Parameters**

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

#### unregister\_tool\_info

`tai42_contract.tools.AppTools.unregister_tool_info`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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` | — | — |

## ClientTool

`tai42_contract.tools.ClientTool`

```python theme={null}
class ClientTool(Protocol)
```

A registered tool bound for in-process use by an agent engine, framework-neutral.

`name` is the full registered name (never truncated); `input_schema` is the JSON Schema of
the arguments, the schema the MCP edge advertises. `invoke` returns the tool's value with
secrets masked, or a `SuspendedInteraction` / `ResumeBuffered` (by type, unadapted) when a
tool that declares it can pause parked; it raises `ClientToolError` for a failure the
model should see (the body raised, a driver reached a FAILED terminal, the result cannot be
JSON-encoded, the arguments do not validate), and raises every other error raw (tier refusal,
authorization, unknown or vanished tool, a park signal from a tool that does not declare it can
pause — `UndeclaredPauseError` — cancellation).

### Members

#### name

`tai42_contract.tools.ClientTool.name`

```python theme={null}
name: str
```

The full registered tool name.

#### description

`tai42_contract.tools.ClientTool.description`

```python theme={null}
description: str
```

The tool's description, as the model reads it.

#### input\_schema

`tai42_contract.tools.ClientTool.input_schema`

```python theme={null}
input_schema: dict[str, Any]
```

The JSON Schema of the tool's arguments.

#### invoke

`tai42_contract.tools.ClientTool.invoke`

```python theme={null}
async invoke(self, arguments: Mapping[str, Any]) -> Any
```

Run the tool once with `arguments`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `arguments` | `Mapping[str, Any]` | — | — |

## ClientToolError

`tai42_contract.tools.ClientToolError`

```python theme={null}
class ClientToolError(Exception)
```

One call's model-visible failure; the message is worded for the model and names the tool.

**Attributes**

| Attribute | Type |
| - | - |
| `tool_name` | — |

## NestedDoorFrameError

`tai42_contract.tools.call_frame.NestedDoorFrameError`

```python theme={null}
class NestedDoorFrameError(RuntimeError)
```

A DOOR-form `tool_call_frame` was opened on a non-fresh run context.

A door frame is the outermost minting frame of a run: it opens only when no run is already in
flight in the current context. This is raised when the door's task inherited a running run's
ambient context — a non-empty call chain, or an already-bound run-delivery context — which
means the task was spawned as a new root of execution WITHOUT a fresh context. Minting the
run's delivery identity under an inherited one would key the new run's terminal to the caller's
run instead of to the door's own completion, so the frame refuses to open.

## RunDelivery

`tai42_contract.tools.call_frame.RunDelivery`

```python theme={null}
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 `DeliveryAddress`
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` | `DeliveryAddress \| None` |

## StateTemplateDetachReferee

`tai42_contract.tools.StateTemplateDetachReferee`

```python theme={null}
StateTemplateDetachReferee = Callable[[str, str], Awaitable[list[str]]]
```

## ToolAlreadyRegisteredError

`tai42_contract.tools.ToolAlreadyRegisteredError`

```python theme={null}
class ToolAlreadyRegisteredError(ValueError)
```

A tool of this name is already bound on the live tool surface.

**Attributes**

| Attribute | Type |
| - | - |
| `name` | — |

## ToolDeleteReferee

`tai42_contract.tools.ToolDeleteReferee`

```python theme={null}
ToolDeleteReferee = Callable[[str], Awaitable[list[str]]]
```

## ToolInfo

`tai42_contract.tools.ToolInfo`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
ToolRefsExtractor = Callable[[dict[str, Any]], Iterable[str]]
```

## ToolRenameReferee

`tai42_contract.tools.ToolRenameReferee`

```python theme={null}
ToolRenameReferee = Callable[[str], Awaitable[list[str]]]
```

## ToolRetryBackoff

`tai42_contract.tools.retry.ToolRetryBackoff`

```python theme={null}
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`

```python theme={null}
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` |

## UndeclaredPauseError

`tai42_contract.tools.meta.UndeclaredPauseError`

```python theme={null}
class UndeclaredPauseError(RuntimeError)
```

A tool that does not declare `TOOL_META_PAUSES` returned a park signal.

Stamped `unknown`: no member of the taxonomy names a registration fault, and `unknown`
is never retryable, so no retry policy re-fires the tool body whose park already happened.

**Attributes**

| Attribute | Type |
| - | - |
| `tool` | — |

## current\_call\_chain

`tai42_contract.tools.call_frame.current_call_chain`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
get_run_delivery() -> DeliveryAddress | 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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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`

```python theme={null}
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` | — |


# Versioning (tai42_contract.versioning)
Source: https://docs.tai42.ai/reference/python-sdk/contract-versioning

The VersionedStore primitive behind presets and policies.

The generic versioned-document store contract.

A `kind`-discriminated, body-opaque persistence primitive: append-only version
rows over an opaque JSONB `body`, an active-version pointer, and rollback. The
store knows NOTHING about presets/policies/agents — those are typed VIEWS layered
on top. Identity is `(kind, name)` throughout; every write is one transaction.

This package holds the `VersionedStore` Protocol plus its record models
(`DocumentRecord`, `DocumentVersion`) and typed errors. It is
reached from the assembled facade as `app.versioning.store` (see
`AppVersioning`).

## DocumentExistsError

`tai42_contract.versioning.errors.DocumentExistsError`

```python theme={null}
class DocumentExistsError(DocumentStoreError)
```

A live document already exists for `(kind, name)` (create would collide).

## DocumentNotFoundError

`tai42_contract.versioning.errors.DocumentNotFoundError`

```python theme={null}
class DocumentNotFoundError(DocumentStoreError)
```

No active document for `(kind, name)`.

## DocumentRecord

`tai42_contract.versioning.models.DocumentRecord`

```python theme={null}
class DocumentRecord(BaseModel)
```

A versioned document's live record: its identity plus the active pointer.

`active_version` names the version currently served for `(kind, name)`;
rollback re-points it without copying data. `is_active` is the soft-delete
flag — a soft-deleted document keeps its version history (audit) but drops out
of `list`/`get`. `created_at` is an ISO-8601 timestamp string.

**Attributes**

| Attribute | Type |
| - | - |
| `kind` | `str` |
| `name` | `str` |
| `active_version` | `int` |
| `is_active` | `bool` |
| `created_at` | `str` |

## DocumentStoreError

`tai42_contract.versioning.errors.DocumentStoreError`

```python theme={null}
class DocumentStoreError(Exception)
```

Base for versioned-document store failures, carrying `(kind, name)`.

**Attributes**

| Attribute | Type |
| - | - |
| `kind` | — |
| `name` | — |

## DocumentVersion

`tai42_contract.versioning.models.DocumentVersion`

```python theme={null}
class DocumentVersion(BaseModel)
```

One immutable version row: the opaque `body` plus its version number.

A version is append-only — once written, its `version`, `body`, `tags`,
and `created_at` never change. `tags` is a generic per-version label for
grouping versions (release/grouping labels); it is kind-agnostic and carries
no product meaning (distinct from any categorization a `kind`'s body may
hold). `is_current` is a read-time projection of the owning record's
`active_version` — the store sets it `True` on the active version when it
lists/returns versions; it is not stored on the row. `created_at` is an
ISO-8601 timestamp string.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `version` | `int` |
| `body` | `dict[str, Any]` |
| `tags` | `list[str]` |
| `created_at` | `str` |
| `is_current` | `bool` |

## DocumentVersionNotFoundError

`tai42_contract.versioning.errors.DocumentVersionNotFoundError`

```python theme={null}
class DocumentVersionNotFoundError(DocumentStoreError)
```

No version `version` exists for the `(kind, name)` document.

`version` is carried when known (the version-specific ops always know it);
the `(kind, name)` identity is always present, as for the other store errors.

**Attributes**

| Attribute | Type |
| - | - |
| `version` | — |

## VersionedStore

`tai42_contract.versioning.VersionedStore`

```python theme={null}
class VersionedStore(Protocol)
```

Kind-discriminated, body-opaque version store. Identity is `(kind, name)`.

The `body` is opaque `dict`/JSONB — the store never inspects it; the caller
(a typed view) owns its shape. Every method raises loudly on a missing,
duplicate, or invalid target — never a silent default. `tags` is the generic
per-version grouping label (see `DocumentVersion`), distinct from any
categorization a `kind`'s body may carry.

A write method (`create`, `save_version`, `delete`,
`rollback`) accepts an optional `tx` — the handle from an open
`transaction`. Passed, the write runs WITHIN that unit of work and commits
or rolls back with it; omitted, the write is self-contained and atomic on its own.

### Members

#### transaction

`tai42_contract.versioning.VersionedStore.transaction`

```python theme={null}
transaction(self) -> AbstractAsyncContextManager[VersionedStoreTransaction]
```

Open a single-backend unit of work: `async with store.transaction() as tx`.

Every store write performed with the yielded `tx` (passed as `tx=` to the
write methods) commits or rolls back TOGETHER — a clean exit commits, an
exception rolls the whole scope back. A pure durability primitive over the one
backend: it carries no audit or domain awareness, and yields an opaque handle
the caller only threads back into the write methods.

#### create

`tai42_contract.versioning.VersionedStore.create`

```python theme={null}
async create(
    self,
    kind: str,
    name: str,
    body: dict[str, Any],
    tags: list[str] | None = None,
    *,
    tx: VersionedStoreTransaction | None = None,
) -> DocumentRecord
```

Insert a new document at `active_version = 1` plus its version 1, one transaction.

Raise `DocumentExistsError` if `(kind, name)` is
already a live document. Runs within `tx` when one is supplied; the
duplicate raise MUST leave a caller-supplied `tx` usable — losing a
concurrent create is an outcome, never a poisoned unit of work.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `str` | — | — |
| `name` | `str` | — | — |
| `body` | `dict[str, Any]` | — | — |
| `tags` | `list[str] \| None` | `None` | — |
| `tx` | `VersionedStoreTransaction \| None` | `None` | — |

#### save\_version

`tai42_contract.versioning.VersionedStore.save_version`

```python theme={null}
async save_version(
    self,
    kind: str,
    name: str,
    body: dict[str, Any],
    tags: list[str] | None = None,
    *,
    tx: VersionedStoreTransaction | None = None,
) -> DocumentVersion
```

Append a new version and bump the active pointer to it, one transaction.

`new_version = max(version) + 1`, NOT `active_version + 1`. A partial failure rolls
the whole save back — no orphan version, no half-bumped pointer. Raise
`DocumentNotFoundError` if absent. Runs within `tx` when one is supplied.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `str` | — | — |
| `name` | `str` | — | — |
| `body` | `dict[str, Any]` | — | — |
| `tags` | `list[str] \| None` | `None` | — |
| `tx` | `VersionedStoreTransaction \| None` | `None` | — |

#### list

`tai42_contract.versioning.VersionedStore.list`

```python theme={null}
async list(self, kind: str) -> list[DocumentRecord]
```

List the active (non-soft-deleted) documents of `kind`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `str` | — | — |

#### get

`tai42_contract.versioning.VersionedStore.get`

```python theme={null}
async get(self, kind: str, name: str) -> DocumentRecord
```

Fetch the active record for `(kind, name)`.

Raise `DocumentNotFoundError` if absent.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `str` | — | — |
| `name` | `str` | — | — |

#### get\_active\_body

`tai42_contract.versioning.VersionedStore.get_active_body`

```python theme={null}
async get_active_body(
    self,
    kind: str,
    name: str,
    *,
    tx: VersionedStoreTransaction | None = None,
    for_update: bool = False,
) -> dict[str, Any]
```

Return the `body` of the active version for `(kind, name)`.

Raise `DocumentNotFoundError` if absent.
Passed a `tx`, the read rides that transaction's connection so a
read-modify-write can lock and mutate the row on one connection (no second pooled
connection while the transaction is open). With `for_update=True` it takes a
`SELECT ... FOR UPDATE` row lock on the active document so concurrent writers
serialize — the lock is meaningful only inside a transaction, so `for_update`
REQUIRES a `tx` and raises loudly without one. Omitting both preserves the
stand-alone read.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `str` | — | — |
| `name` | `str` | — | — |
| `tx` | `VersionedStoreTransaction \| None` | `None` | — |
| `for_update` | `bool` | `False` | — |

#### list\_versions

`tai42_contract.versioning.VersionedStore.list_versions`

```python theme={null}
async list_versions(self, kind: str, name: str) -> list[DocumentVersion]
```

List every version of `(kind, name)` with its `DocumentVersion.is_current` signal.

`is_current` is derived from `active_version`. Raise `DocumentNotFoundError` if the
document is absent.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `str` | — | — |
| `name` | `str` | — | — |

#### get\_version

`tai42_contract.versioning.VersionedStore.get_version`

```python theme={null}
async get_version(
    self,
    kind: str,
    name: str,
    version: int,
    *,
    tx: VersionedStoreTransaction | None = None,
) -> DocumentVersion
```

Fetch one version.

Raise `DocumentVersionNotFoundError` if that
version does not exist. Passed a `tx`, the read rides that transaction's
connection rather than opening a second pooled one.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `str` | — | — |
| `name` | `str` | — | — |
| `version` | `int` | — | — |
| `tx` | `VersionedStoreTransaction \| None` | `None` | — |

#### rollback

`tai42_contract.versioning.VersionedStore.rollback`

```python theme={null}
async rollback(
    self,
    kind: str,
    name: str,
    version: int,
    *,
    tx: VersionedStoreTransaction | None = None,
) -> DocumentRecord
```

Re-point `active_version` to `version` (NO data copy).

Raise `DocumentVersionNotFoundError` if that version does not exist. Runs
within `tx` when one is supplied.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `str` | — | — |
| `name` | `str` | — | — |
| `version` | `int` | — | — |
| `tx` | `VersionedStoreTransaction \| None` | `None` | — |

#### soft\_delete

`tai42_contract.versioning.VersionedStore.soft_delete`

```python theme={null}
async soft_delete(self, kind: str, name: str) -> None
```

Set `is_active = False`, keeping the version history (audit).

The document drops out of `list`/`get` but its rows survive.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `str` | — | — |
| `name` | `str` | — | — |

#### delete

`tai42_contract.versioning.VersionedStore.delete`

```python theme={null}
async delete(self, kind: str, name: str, *, tx: VersionedStoreTransaction | None = None) -> None
```

HARD delete, DISTINCT from `soft_delete`.

Remove ONLY the ACTIVE
document row for `(kind, name)` AND its version rows, so nothing of the
active document survives; a soft-deleted ghost of the same name is left
untouched. Raise `DocumentNotFoundError` if there is no active row.
Used to roll a never-succeeded create fully back and to remove a conflicted
record without leaving the ghost + spurious history a soft delete would. Runs
within `tx` when one is supplied.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `str` | — | — |
| `name` | `str` | — | — |
| `tx` | `VersionedStoreTransaction \| None` | `None` | — |

#### rename

`tai42_contract.versioning.VersionedStore.rename`

```python theme={null}
async rename(self, kind: str, name: str, new_name: str) -> DocumentRecord
```

Re-key the ACTIVE document `(kind, name)` to `(kind, new_name)` in one atomic write.

The whole version history, every per-version `tags` label, and
the `active_version` pointer move untouched — versions key on the document,
not the name, so nothing is copied. The `body` is never inspected (the store
stays body-opaque). A soft-deleted ghost named `new_name` does NOT block (the
same partial-unique identity rule `create` follows), and a soft-deleted
ghost of `name` is left untouched as audit history. Raise
`DocumentNotFoundError` if `(kind, name)` has no active row; raise
`DocumentExistsError` (carrying `new_name`) if `(kind, new_name)` is
already a live document.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `str` | — | — |
| `name` | `str` | — | — |
| `new_name` | `str` | — | — |

## VersionedStoreTransaction

`tai42_contract.versioning.VersionedStoreTransaction`

```python theme={null}
class VersionedStoreTransaction(Protocol)
```

Opaque unit-of-work handle yielded by `VersionedStore.transaction`.

A pure durability token exposing NO operations of its own: a caller only passes it
back to a write method's `tx=` parameter so that write joins the open
transaction. The concrete store owns the handle's real shape (its pooled
connection); the token carries no audit or domain awareness.


# Python SDK
Source: https://docs.tai42.ai/reference/python-sdk/index

The generated Python SDK reference.

The Python SDK reference is generated from the docstrings of the public `tai42_contract`, `tai42_kit`, and skeleton APIs.

> **[App facade](/reference/python-sdk/contract-app)**
>
> The assembled TaiApp facade and its namespaces.

> **[Agents](/reference/python-sdk/contract-agent)**
>
> The Agent base class plugin authors subclass.

> **[Versioning](/reference/python-sdk/contract-versioning)**
>
> The VersionedStore primitive behind presets.

> **[Presets](/reference/python-sdk/contract-presets)**
>
> The PresetStore protocol and preset models.

> **[Tools](/reference/python-sdk/contract-tools)**
>
> Tool registration types and the app tools namespace.

> **[LLM factories](/reference/python-sdk/kit-llm)**
>
> LLM, embedding, checkpoint, and store factories.


# Checkpoint stores (tai42_kit.llm.checkpoint)
Source: https://docs.tai42.ai/reference/python-sdk/kit-checkpoint

The checkpoint-store seam: the provider registry and its facts, the resource and retention seams, and the protocols and helpers a store's registration builds on.

Checkpoint savers for LLM graph state: the provider registry, the per-loop registry, and the retention seams.

A checkpoint store is a registration of `CheckpointProvider` (its name, its facts, the hooks the
kit applies its features through); the kit's built-in stores register at this package's import. The
owner-declared thread retention, the finished-thread ledger calls, the live-thread filter registry and
the pieces a store's registration builds on (the shared-value chunker and resolver, the value store
and ledger protocols, the msgpack value encoding) are exported here.

## CHECKPOINT\_STORE\_FORMAT\_GENERATION

`tai42_kit.llm.checkpoint.store_format.CHECKPOINT_STORE_FORMAT_GENERATION`

```python theme={null}
CHECKPOINT_STORE_FORMAT_GENERATION: Final[int] = 4
```

## REDIS\_CHECKPOINT\_NOT\_CONFIGURED\_MESSAGE

`tai42_kit.llm.checkpoint.stores.redis.REDIS_CHECKPOINT_NOT_CONFIGURED_MESSAGE`

```python theme={null}
REDIS_CHECKPOINT_NOT_CONFIGURED_MESSAGE: Final = not_configured_message('the Redis checkpoint', 'LLM_PROVIDER_CHECKPOINT_CONN_STRING', 'the base Redis URL REDIS_URL / TAI_DEFAULT_REDIS_URL') + ' The target Redis must provide the JSON and search modules (RedisJSON +' + ' RediSearch); a plain Redis fails mid-run on FT.* commands.'
```

## REFERENCING\_TYPE\_SUFFIX

`tai42_kit.llm.checkpoint.checkpoint.REFERENCING_TYPE_SUFFIX`

```python theme={null}
REFERENCING_TYPE_SUFFIX: Final = '+ref'
```

## ChannelStorage

`tai42_kit.llm.checkpoint.providers.ChannelStorage`

```python theme={null}
ChannelStorage = Literal['per_checkpoint', 'per_version']
```

## CheckpointCodec

`tai42_kit.llm.checkpoint.envelope.CheckpointCodec`

```python theme={null}
class CheckpointCodec(Protocol)
```

A codec the serialization guard installs around a saver's serializer.

Every value the saver stores is written by the codec, and read back by it: a value the kit
encoded ahead of the saver takes the codec's `inline_form`.

### Members

#### dumps\_typed

`tai42_kit.llm.checkpoint.envelope.CheckpointCodec.dumps_typed`

```python theme={null}
dumps_typed(self, inner: Any, obj: Any) -> tuple[str, bytes]
```

Encode `obj` through `inner`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `inner` | `Any` | — | — |
| `obj` | `Any` | — | — |

#### inline\_form

`tai42_kit.llm.checkpoint.envelope.CheckpointCodec.inline_form`

```python theme={null}
inline_form(self, inner: Any, encoded: tuple[str, bytes]) -> tuple[str, bytes]
```

The `(type, bytes)` the saver stores for a value `inner` encoded as `encoded`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `inner` | `Any` | — | — |
| `encoded` | `tuple[str, bytes]` | — | — |

#### loads\_typed

`tai42_kit.llm.checkpoint.envelope.CheckpointCodec.loads_typed`

```python theme={null}
loads_typed(self, inner: Any, data: tuple[str, bytes]) -> Any
```

Decode `data` through `inner`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `inner` | `Any` | — | — |
| `data` | `tuple[str, bytes]` | — | — |

## CheckpointProvider

`tai42_kit.llm.checkpoint.providers.CheckpointProvider`

```python theme={null}
class CheckpointProvider(ABC)
```

One checkpoint store's registration: its name, its facts, and the hooks the kit applies its features through.

The kit calls the hooks and applies everything else itself, the same way for every store: the
serialization guard, large values stored once per thread, the store-format gate, the retention
views and the sweep. A hook receives the settings it needs as arguments.

**Attributes**

| Attribute | Type |
| - | - |
| `name` | `str` |
| `facts` | `CheckpointProviderFacts` |

### Members

#### open

`tai42_kit.llm.checkpoint.providers.CheckpointProvider.open`

```python theme={null}
async open(self, conn_string: str | None) -> tuple[CheckpointResource, Callable[[], Awaitable[None]]]
```

Open the store: its handle, its finished-thread ledger and its per-thread value store, set up.

Returns the resource and the function that closes it. A `None` conn string means the store's
default connection, or raises naming the setting to set.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `conn_string` | `str \| None` | — | — |

#### saver

`tai42_kit.llm.checkpoint.providers.CheckpointProvider.saver`

```python theme={null}
saver(self, resource: CheckpointResource) -> BaseCheckpointSaver
```

The store's saver over `resource`, as the library builds it; the kit guards and wraps it.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `resource` | `CheckpointResource` | — | — |

#### saver\_with\_waiting

`tai42_kit.llm.checkpoint.providers.CheckpointProvider.saver_with_waiting`

```python theme={null}
async saver_with_waiting(self, resource: CheckpointResource, waiting_minutes: int) -> tuple[BaseCheckpointSaver, CheckpointValueStore]
```

A saver over `resource` whose writes carry `waiting_minutes` as their key TTL, with its value store.

The value store's writes carry the same TTL over the store's own key space. Required when the
store's retention is `native_ttl`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `resource` | `CheckpointResource` | — | — |
| `waiting_minutes` | `int` | — | — |

#### serializer

`tai42_kit.llm.checkpoint.providers.CheckpointProvider.serializer`

```python theme={null}
serializer(self, saver: BaseCheckpointSaver, compress_threshold: int | None) -> tuple[Any, CheckpointCodec | None]
```

The serializer the kit guards on `saver` and the codec it installs around it.

The codec writes and reads back every value the saver stores, a value the kit encoded ahead of
the saver included. `compress_threshold` is `LLM_PROVIDER_CHECKPOINT_INLINE_COMPRESS_BYTES`.
Default: the saver's own serializer and no codec.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `saver` | `BaseCheckpointSaver` | — | — |
| `compress_threshold` | `int \| None` | — | — |

#### value\_encoding

`tai42_kit.llm.checkpoint.providers.CheckpointProvider.value_encoding`

```python theme={null}
value_encoding(self, saver: BaseCheckpointSaver, compress_threshold: int | None) -> ValueEncoding
```

How this store encodes a value for the chunker, its value store and the resolver.

`saver` carries the guarded serializer.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `saver` | `BaseCheckpointSaver` | — | — |
| `compress_threshold` | `int \| None` | — | — |

#### prepare\_checkpoint

`tai42_kit.llm.checkpoint.providers.CheckpointProvider.prepare_checkpoint`

```python theme={null}
async prepare_checkpoint(
    self,
    write: CheckpointWrite,
    checkpoint: Checkpoint,
    new_versions: ChannelVersions,
) -> tuple[Checkpoint, ChannelVersions]
```

The checkpoint and versions the saver is handed; every value they reference is held when this returns.

Default: the kit's preparation for `facts`' `channel_storage`. A store overrides it
only with knowledge of its own saver's storage.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `write` | `CheckpointWrite` | — | — |
| `checkpoint` | `Checkpoint` | — | — |
| `new_versions` | `ChannelVersions` | — | — |

#### prepare\_writes

`tai42_kit.llm.checkpoint.providers.CheckpointProvider.prepare_writes`

```python theme={null}
async prepare_writes(self, write: CheckpointWrite, writes: Sequence[tuple[str, Any]]) -> Sequence[tuple[str, Any]]
```

The pending writes the saver is handed; every value they reference is held when this returns.

Default: every write value chunked and pre-encoded.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `write` | `CheckpointWrite` | — | — |
| `writes` | `Sequence[tuple[str, Any]]` | — | — |

#### recorded\_generation

`tai42_kit.llm.checkpoint.providers.CheckpointProvider.recorded_generation`

```python theme={null}
async recorded_generation(self, resource: CheckpointResource) -> int | None
```

The store-format generation the store records, or `None` when it records none.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `resource` | `CheckpointResource` | — | — |

#### record\_generation

`tai42_kit.llm.checkpoint.providers.CheckpointProvider.record_generation`

```python theme={null}
async record_generation(self, resource: CheckpointResource, generation: int) -> None
```

Record `generation` unless one is recorded: concurrent first builds keep the first.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `resource` | `CheckpointResource` | — | — |
| `generation` | `int` | — | — |

#### holds\_checkpoints

`tai42_kit.llm.checkpoint.providers.CheckpointProvider.holds_checkpoints`

```python theme={null}
async holds_checkpoints(self, resource: CheckpointResource) -> bool
```

Whether the store holds any checkpoint.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `resource` | `CheckpointResource` | — | — |

## CheckpointProviderFacts

`tai42_kit.llm.checkpoint.providers.CheckpointProviderFacts`

```python theme={null}
class CheckpointProviderFacts
```

What the kit reads about one checkpoint store.

**Attributes**

| Attribute | Type |
| - | - |
| `durable` | `bool` |
| `retention` | `RetentionMode` |
| `channel_storage` | `ChannelStorage` |

## CheckpointReferenceError

`tai42_kit.llm.checkpoint.chunking.CheckpointReferenceError`

```python theme={null}
class CheckpointReferenceError(CheckpointSerializationError)
```

A stored checkpoint references a value its thread's value store does not hold, or holds altered.

## CheckpointResource

`tai42_kit.llm.checkpoint.checkpoint.CheckpointResource`

```python theme={null}
class CheckpointResource
```

The long-lived resource behind one `provider::conn_string` checkpoint store.

`handle` is what the store's registration builds its saver on. `ledger` is the store's
finished-thread ledger and `values` its per-thread value store, both kept in the same store as
the checkpoints.

**Attributes**

| Attribute | Type |
| - | - |
| `provider` | `str` |
| `handle` | `Any` |
| `ledger` | `FinishedThreadLedger` |
| `values` | `CheckpointValueStore` |

## CheckpointSerializationError

`tai42_kit.llm.checkpoint.checkpoint.CheckpointSerializationError`

```python theme={null}
class CheckpointSerializationError(Exception)
```

A checkpoint value could not be stored faithfully, or a stored value could not be read back.

The guard converts ormsgpack's `MsgpackEncodeError` into this typed error so a value
the serializer cannot encode fails loudly — never a silent pickle fallback, never an
opaque engine crash. The checkpoint guard owns the storage integer range: an integer
outside the native msgpack range `[-2**63, 2**64-1]` has no encoding, and the message
NAMES the offending path. A store's codec raises it for a value it cannot store
faithfully and for a stored value it cannot decode.

## CheckpointStoreFormatError

`tai42_kit.llm.checkpoint.store_format.CheckpointStoreFormatError`

```python theme={null}
class CheckpointStoreFormatError(RuntimeError)
```

The checkpoint store holds data written in a format this version does not read.

## CheckpointValueRef

`tai42_kit.llm.checkpoint.chunking.CheckpointValueRef`

```python theme={null}
class CheckpointValueRef
```

A reference to a value stored once in its thread's value store.

`digest`: the SHA-256 (hex) of the value's encoding. `size`: the encoding's length in bytes.
`closure`: the digests of every reference inside that value, transitively.

**Attributes**

| Attribute | Type |
| - | - |
| `digest` | `str` |
| `size` | `int` |
| `closure` | `tuple[str, ...]` |

## CheckpointValueStore

`tai42_kit.llm.checkpoint.value_store.CheckpointValueStore`

```python theme={null}
class CheckpointValueStore(Protocol)
```

Where one checkpoint store keeps its threads' shared values.

### Members

#### touch

`tai42_kit.llm.checkpoint.value_store.CheckpointValueStore.touch`

```python theme={null}
async touch(self, thread_id: str, digests: Collection[str]) -> set[str]
```

Re-arm the retention of the held `digests` of `thread_id`; return those it does not hold.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |
| `digests` | `Collection[str]` | — | — |

#### put

`tai42_kit.llm.checkpoint.value_store.CheckpointValueStore.put`

```python theme={null}
async put(self, thread_id: str, blobs: Mapping[str, StoredBlob]) -> None
```

Store `blobs` (by digest) for `thread_id`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |
| `blobs` | `Mapping[str, StoredBlob]` | — | — |

#### get

`tai42_kit.llm.checkpoint.value_store.CheckpointValueStore.get`

```python theme={null}
async get(self, thread_id: str, digests: Collection[str]) -> dict[str, StoredBlob]
```

The held blobs among `digests` of `thread_id`; a digest it does not hold is absent.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |
| `digests` | `Collection[str]` | — | — |

#### held\_digests

`tai42_kit.llm.checkpoint.value_store.CheckpointValueStore.held_digests`

```python theme={null}
async held_digests(self, thread_id: str) -> set[str]
```

Every digest `thread_id` holds.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |

#### delete\_thread

`tai42_kit.llm.checkpoint.value_store.CheckpointValueStore.delete_thread`

```python theme={null}
async delete_thread(self, thread_id: str) -> None
```

Delete every value `thread_id` holds.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |

## CheckpointWrite

`tai42_kit.llm.checkpoint.providers.CheckpointWrite`

```python theme={null}
class CheckpointWrite
```

What the kit hands a store's write preparation: the thread's value store and the kit's tools.

`saver` is the store's own saver, `values` the value store the write's large values go to,
`encoding` the store's value encoding and `threshold` the encoded size above which a value is
stored once (a preparation runs only where sharing is on).

**Attributes**

| Attribute | Type |
| - | - |
| `saver` | `BaseCheckpointSaver` |
| `config` | `RunnableConfig` |
| `thread_id` | `str` |
| `values` | `CheckpointValueStore` |
| `encoding` | `ValueEncoding` |
| `threshold` | `int` |

### Members

#### chunker

`tai42_kit.llm.checkpoint.providers.CheckpointWrite.chunker`

```python theme={null}
chunker(self) -> ValueChunker
```

A chunker over the store's encoding and the threshold.

#### inline\_form

`tai42_kit.llm.checkpoint.providers.CheckpointWrite.inline_form`

```python theme={null}
inline_form(self, encoded: tuple[str, bytes]) -> tuple[str, bytes]
```

The `(type, bytes)` to hand the saver for a value the store's encoding encoded as `encoded`.

It is the form the saver's guarded serializer stores, so the saver reads it back.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `encoded` | `tuple[str, bytes]` | — | — |

#### store

`tai42_kit.llm.checkpoint.providers.CheckpointWrite.store`

```python theme={null}
async store(self, digests: Collection[str], blobs: Mapping[str, tuple[str, bytes]]) -> None
```

Re-arm every digest of `digests` and store the missing ones from `blobs`, in their store form.

A digest the value store does not hold and `blobs` does not encode raises
`CheckpointReferenceError` naming the thread and the digest.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `digests` | `Collection[str]` | — | — |
| `blobs` | `Mapping[str, tuple[str, bytes]]` | — | — |

## FinishedThreadLedger

`tai42_kit.llm.checkpoint.ledger.FinishedThreadLedger`

```python theme={null}
class FinishedThreadLedger(Protocol)
```

The per-thread retention record of one checkpoint store.

It holds the finished marks and their due times, the declared waiting retentions, and lists the
threads past their waiting horizon. Every method that takes thread ids takes any sequence; an
empty one changes nothing, on every provider.

### Members

#### start

`tai42_kit.llm.checkpoint.ledger.FinishedThreadLedger.start`

```python theme={null}
async start(self, thread_ids: Sequence[str], retention: ThreadRetention | None) -> None
```

A run starts on `thread_ids`: remove their finished mark and record their declared waiting.

The waiting is recorded wherever the store's saver does not carry it as a key TTL; `None`
(the platform's) removes a recorded one. A store whose saver stamps the waiting as the TTL of
every key it writes records nothing.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_ids` | `Sequence[str]` | — | — |
| `retention` | `ThreadRetention \| None` | — | — |

#### mark

`tai42_kit.llm.checkpoint.ledger.FinishedThreadLedger.mark`

```python theme={null}
async mark(self, thread_ids: Sequence[str], due_at: datetime) -> None
```

Record `thread_ids` as finished and deletable at or after `due_at` (a later mark moves it).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_ids` | `Sequence[str]` | — | — |
| `due_at` | `datetime` | — | — |

#### finished\_before

`tai42_kit.llm.checkpoint.ledger.FinishedThreadLedger.finished_before`

```python theme={null}
async finished_before(self, cutoff: datetime, limit: int) -> list[str]
```

Up to `limit` thread ids due at or before `cutoff`, earliest due first.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `cutoff` | `datetime` | — | — |
| `limit` | `int` | — | — |

#### forget

`tai42_kit.llm.checkpoint.ledger.FinishedThreadLedger.forget`

```python theme={null}
async forget(self, thread_ids: Sequence[str]) -> None
```

Remove `thread_ids` from the ledger: their finished mark and their declared waiting.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_ids` | `Sequence[str]` | — | — |

#### declared\_waiting

`tai42_kit.llm.checkpoint.ledger.FinishedThreadLedger.declared_waiting`

```python theme={null}
async declared_waiting(self, thread_ids: Sequence[str]) -> dict[str, int]
```

The recorded declared waiting minutes of those of `thread_ids` that have one.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_ids` | `Sequence[str]` | — | — |

#### stale\_threads

`tai42_kit.llm.checkpoint.ledger.FinishedThreadLedger.stale_threads`

```python theme={null}
async stale_threads(self, saver: BaseCheckpointSaver, *, now: datetime, default_minutes: int) -> list[str]
```

The threads whose newest checkpoint is older than their waiting retention before `now`, by id.

A thread's waiting retention is the one its owner declared at run start, else
`default_minutes`; its newest checkpoint is the newest in any of its namespaces. A store with
an index of its own answers from it; otherwise `saver` (the store's own) is walked. `now`
must be timezone-aware.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `saver` | `BaseCheckpointSaver` | — | — |
| `now` | `datetime` | — | — |
| `default_minutes` | `int` | — | — |

## LiveThreadFilter

`tai42_kit.llm.checkpoint.liveness.LiveThreadFilter`

```python theme={null}
LiveThreadFilter = Callable[[str, str | None, Sequence[str]], Awaitable[Collection[str]]]
```

## MsgpackValueEncoding

`tai42_kit.llm.checkpoint.value_encoding.MsgpackValueEncoding`

```python theme={null}
class MsgpackValueEncoding
```

A store's msgpack encoding, for the chunker, its value store and the resolver.

### Members

#### encode

`tai42_kit.llm.checkpoint.value_encoding.MsgpackValueEncoding.encode`

```python theme={null}
encode(self, value: Any) -> tuple[str, bytes]
```

The `(type, bytes)` the library serializer writes for `value`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `Any` | — | — |

#### reference

`tai42_kit.llm.checkpoint.value_encoding.MsgpackValueEncoding.reference`

```python theme={null}
reference(self, ref: CheckpointValueRef) -> Any
```

The `ref` envelope, a plain dictionary in the msgpack blob.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `ref` | `CheckpointValueRef` | — | — |

#### as\_reference

`tai42_kit.llm.checkpoint.value_encoding.MsgpackValueEncoding.as_reference`

```python theme={null}
as_reference(self, value: Any) -> CheckpointValueRef | None
```

A reference as msgpack reads it back: the `ref` envelope dictionary.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `Any` | — | — |

#### store\_form

`tai42_kit.llm.checkpoint.value_encoding.MsgpackValueEncoding.store_form`

```python theme={null}
store_form(self, encoded: tuple[str, bytes]) -> StoredBlob
```

The blob, zlib compressed under its own type tag when it is msgpack above the compress threshold.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `encoded` | `tuple[str, bytes]` | — | — |

#### decode

`tai42_kit.llm.checkpoint.value_encoding.MsgpackValueEncoding.decode`

```python theme={null}
decode(self, blob: StoredBlob, ref: CheckpointValueRef, thread_id: Any) -> Any
```

Decompress and decode `blob`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `blob` | `StoredBlob` | — | — |
| `ref` | `CheckpointValueRef` | — | — |
| `thread_id` | `Any` | — | — |

## PreEncodedCheckpoint

`tai42_kit.llm.checkpoint.checkpoint.PreEncodedCheckpoint`

```python theme={null}
class PreEncodedCheckpoint(dict[str, Any])
```

A checkpoint the kit already encoded whole, carrying the checkpoint's keys for the library saver.

The library saver reads the checkpoint's id and copies it before handing it to its serializer;
the copy keeps the encoding, and the serializer returns `encoded` as it is. `references`: as
`PreEncodedValue`.

**Attributes**

| Attribute | Type |
| - | - |
| `encoded` | — |
| `references` | — |

### Members

#### copy

`tai42_kit.llm.checkpoint.checkpoint.PreEncodedCheckpoint.copy`

```python theme={null}
copy(self) -> PreEncodedCheckpoint
```

A shallow copy that keeps the encoding.

## PreEncodedValue

`tai42_kit.llm.checkpoint.checkpoint.PreEncodedValue`

```python theme={null}
class PreEncodedValue
```

A checkpoint value the kit already encoded: the saver's serializer returns `encoded` as it is.

`references`: the value holds a reference to a shared value, so its type tag carries
`REFERENCING_TYPE_SUFFIX`.

**Attributes**

| Attribute | Type |
| - | - |
| `encoded` | — |
| `references` | — |

## RetentionMode

`tai42_kit.llm.checkpoint.providers.RetentionMode`

```python theme={null}
RetentionMode = Literal['native_ttl', 'sweep', 'process']
```

## SharedSnapshot

`tai42_kit.llm.checkpoint.chunking.SharedSnapshot`

```python theme={null}
class SharedSnapshot(_DeltaSnapshot)
```

A `_DeltaSnapshot` whose payload holds a reference.

## StoredBlob

`tai42_kit.llm.checkpoint.value_store.StoredBlob`

```python theme={null}
class StoredBlob
```

A value as its thread's value store holds it: a type tag and the stored bytes.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `str` |
| `data` | `bytes` |

## ThreadRetention

`tai42_kit.llm.checkpoint.retention.ThreadRetention`

```python theme={null}
class ThreadRetention
```

How long a checkpoint thread is kept, in minutes, bounded by the platform's values.

`waiting_minutes`: after its last write, while its owner may still continue it.
`finished_minutes`: after its owner marked it finished.

Every value is checked when it is built, so every seam that takes one (the saver views, the
finished-thread ledger, the park horizon) holds the platform's ceiling. Raises
`ThreadRetentionError` for a value that is not positive, a value above the platform's
for its horizon, or a finished longer than the waiting.

**Attributes**

| Attribute | Type |
| - | - |
| `waiting_minutes` | `int` |
| `finished_minutes` | `int` |

## ThreadRetentionError

`tai42_kit.llm.checkpoint.retention.ThreadRetentionError`

```python theme={null}
class ThreadRetentionError(ValueError)
```

A declared checkpoint retention is out of bounds; the message names the value and the bound it broke.

## UnknownCheckpointProviderError

`tai42_kit.llm.checkpoint.providers.UnknownCheckpointProviderError`

```python theme={null}
class UnknownCheckpointProviderError(ValueError)
```

A checkpoint provider name no registration holds.

## ValueChunker

`tai42_kit.llm.checkpoint.chunking.ValueChunker`

```python theme={null}
class ValueChunker
```

Chunk values above `threshold` into blobs; `None` keeps every value inline.

`blobs` maps every digest the chunked values reference, at any depth, to its encoding.

**Attributes**

| Attribute | Type |
| - | - |
| `blobs` | `dict[str, tuple[str, bytes]]` |

### Members

#### chunk

`tai42_kit.llm.checkpoint.chunking.ValueChunker.chunk`

```python theme={null}
chunk(self, value: Any) -> tuple[Any, tuple[str, bytes]]
```

`value` with its sub-values above the threshold replaced by references, and its encoding.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `Any` | — | — |

## ValueEncoding

`tai42_kit.llm.checkpoint.chunking.ValueEncoding`

```python theme={null}
class ValueEncoding(Protocol)
```

One store's encoding of checkpoint values, as the chunker and the resolver use it.

### Members

#### encode

`tai42_kit.llm.checkpoint.chunking.ValueEncoding.encode`

```python theme={null}
encode(self, value: Any) -> tuple[str, bytes]
```

The `(type, bytes)` the store's serializer writes for `value`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `Any` | — | — |

#### reference

`tai42_kit.llm.checkpoint.chunking.ValueEncoding.reference`

```python theme={null}
reference(self, ref: CheckpointValueRef) -> Any
```

The value a checkpoint stores in place of the value `ref` names.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `ref` | `CheckpointValueRef` | — | — |

#### as\_reference

`tai42_kit.llm.checkpoint.chunking.ValueEncoding.as_reference`

```python theme={null}
as_reference(self, value: Any) -> CheckpointValueRef | None
```

The reference `value` is as the store reads it back, or `None` when it is none.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `Any` | — | — |

#### store\_form

`tai42_kit.llm.checkpoint.chunking.ValueEncoding.store_form`

```python theme={null}
store_form(self, encoded: tuple[str, bytes]) -> StoredBlob
```

The blob the value store holds for a value encoded as `encoded`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `encoded` | `tuple[str, bytes]` | — | — |

#### decode

`tai42_kit.llm.checkpoint.chunking.ValueEncoding.decode`

```python theme={null}
decode(self, blob: StoredBlob, ref: CheckpointValueRef, thread_id: Any) -> Any
```

The value `blob` holds; a blob whose encoding is not `ref.size` long raises.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `blob` | `StoredBlob` | — | — |
| `ref` | `CheckpointValueRef` | — | — |
| `thread_id` | `Any` | — | — |

## as\_utc

`tai42_kit.llm.checkpoint.ledger.as_utc`

```python theme={null}
as_utc(at: datetime) -> datetime
```

`at` in UTC; a naive time raises `ValueError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `at` | `datetime` | — | — |

## checkpoint\_park\_horizon

`tai42_kit.llm.checkpoint.providers.checkpoint_park_horizon`

```python theme={null}
checkpoint_park_horizon(provider: str, retention: ThreadRetention | None = None) -> timedelta | None
```

How long a parked run's checkpoint is kept on `provider`; `None` when the store does not outlive the process.

On a durable provider a parked thread's last write is its park checkpoint, and the thread is kept its
waiting retention after it — the owner's declared one, else the platform's — so a park may wait at
most that long.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `provider` | `str` | — | — |
| `retention` | `ThreadRetention \| None` | `None` | — |

## checkpoint\_provider

`tai42_kit.llm.checkpoint.providers.checkpoint_provider`

```python theme={null}
checkpoint_provider(name: str) -> CheckpointProvider
```

The registration of `name`; an unknown name raises `UnknownCheckpointProviderError`.

**Parameters**

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

## checkpoint\_provider\_facts

`tai42_kit.llm.checkpoint.providers.checkpoint_provider_facts`

```python theme={null}
checkpoint_provider_facts(provider: str) -> CheckpointProviderFacts
```

Return the facts of `provider`; an unknown name raises `UnknownCheckpointProviderError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `provider` | `str` | — | — |

## checkpoint\_providers

`tai42_kit.llm.checkpoint.providers.checkpoint_providers`

```python theme={null}
checkpoint_providers() -> Mapping[str, CheckpointProviderFacts]
```

A read-only, name-sorted view of every registered provider's facts.

## create\_checkpoint\_resource

`tai42_kit.llm.checkpoint.checkpoint.create_checkpoint_resource`

```python theme={null}
async create_checkpoint_resource(provider: str, conn_string: str | None = None) -> tuple[CheckpointResource, CleanupFn]
```

Open the store `provider` names, and check its store format.

A `None` conn string is the store's default connection (its registration raises, naming the
setting, when it has none). A store holding data written in an older format raises
`CheckpointStoreFormatError` and is closed.

The resource is cached for the life of the app by the registry; its connections stay open.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `provider` | `str` | — | — |
| `conn_string` | `str \| None` | `None` | — |

## create\_saver\_with\_waiting

`tai42_kit.llm.checkpoint.checkpoint.create_saver_with_waiting`

```python theme={null}
async create_saver_with_waiting(provider: str, resource: CheckpointResource, waiting_minutes: int) -> BaseCheckpointSaver
```

A saver over `resource` whose writes carry `waiting_minutes` as their key TTL, guarded and wrapped.

It reads, writes and deletes what the resource's own saver does, its shared values included; only
the TTL it stamps differs.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `provider` | `str` | — | — |
| `resource` | `CheckpointResource` | — | — |
| `waiting_minutes` | `int` | — | — |

## durable\_checkpoint\_providers

`tai42_kit.llm.checkpoint.providers.durable_checkpoint_providers`

```python theme={null}
durable_checkpoint_providers() -> frozenset[str]
```

The providers whose checkpoints survive a process restart.

## envelope\_reference

`tai42_kit.llm.checkpoint.envelope.envelope_reference`

```python theme={null}
envelope_reference(value: Any) -> CheckpointValueRef | None
```

The reference `value` is when it is a `ref` envelope as stored; `None` when it is not one.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `Any` | — | — |

## get\_saver\_from\_resource

`tai42_kit.llm.checkpoint.checkpoint.get_saver_from_resource`

```python theme={null}
get_saver_from_resource(provider: str, resource: CheckpointResource) -> BaseCheckpointSaver
```

The saver a graph checkpoints through on `resource`: the store's saver, guarded and wrapped.

This is the one place a saver is built for a store's own retention, so every saver serializes
through the guard and stores its large values once where sharing is on.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `provider` | `str` | — | — |
| `resource` | `CheckpointResource` | — | — |

## latest\_park\_deadline

`tai42_kit.llm.checkpoint.providers.latest_park_deadline`

```python theme={null}
latest_park_deadline(provider: str, retention: ThreadRetention | None = None) -> datetime | None
```

The latest ask deadline a park taken now on `provider` can serve; `None` on a store dying with the process.

The park's checkpoint is written at or after now and kept `checkpoint_park_horizon` after
it. The platform may deliver an ask's answer or expiry up to its redelivery horizon after the
deadline, so the latest deadline is the checkpoint's earliest expiry less that horizon: a
delivery at any moment the platform still holds the ask finds the checkpoint.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `provider` | `str` | — | — |
| `retention` | `ThreadRetention \| None` | `None` | — |

## live\_thread\_filters

`tai42_kit.llm.checkpoint.liveness.live_thread_filters`

```python theme={null}
live_thread_filters() -> Mapping[str, LiveThreadFilter]
```

A read-only view of the registered filters by owner.

## live\_threads

`tai42_kit.llm.checkpoint.liveness.live_threads`

```python theme={null}
async live_threads(provider: str, conn_string: str | None, thread_ids: Sequence[str]) -> dict[str, str]
```

Map each candidate a registered filter claims to the owner that claimed it.

Every filter is called; a filter's raise propagates.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `provider` | `str` | — | — |
| `conn_string` | `str \| None` | — | — |
| `thread_ids` | `Sequence[str]` | — | — |

## mark\_threads\_active

`tai42_kit.llm.checkpoint.ledger.mark_threads_active`

```python theme={null}
async mark_threads_active(
    thread_ids: Sequence[str],
    *,
    retention: ThreadRetention | None = None,
    provider: str | None = None,
    conn_string: str | None = None,
) -> None
```

Take `thread_ids` out of the ledger before a run starts on them, recording `retention`'s waiting.

`retention` is the owner's declaration for the threads (`None`: the platform's); the store
records its waiting where the waiting horizon is swept. `provider` and `conn_string` resolve
as in `mark_threads_finished`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_ids` | `Sequence[str]` | — | — |
| `retention` | `ThreadRetention \| None` | `None` | — |
| `provider` | `str \| None` | `None` | — |
| `conn_string` | `str \| None` | `None` | — |

## mark\_threads\_finished

`tai42_kit.llm.checkpoint.ledger.mark_threads_finished`

```python theme={null}
async mark_threads_finished(
    thread_ids: Sequence[str],
    *,
    retention: ThreadRetention | None = None,
    provider: str | None = None,
    conn_string: str | None = None,
) -> None
```

Mark `thread_ids` finished now, in the ledger of the store that holds them.

They become deletable their finished retention after now: `retention`'s (the owner's
declaration, see `resolve_retention`), else the
platform's. `provider` and `conn_string` resolve independently: `None` is the deployment's
configured checkpoint provider, respectively its configured connection string. A caller that
checkpoints on a per-run provider passes it. An empty sequence is a no-op; a store error
propagates.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_ids` | `Sequence[str]` | — | — |
| `retention` | `ThreadRetention \| None` | `None` | — |
| `provider` | `str \| None` | `None` | — |
| `conn_string` | `str \| None` | `None` | — |

## platform\_retention

`tai42_kit.llm.checkpoint.retention.platform_retention`

```python theme={null}
platform_retention() -> ThreadRetention
```

The platform's two retention settings: the default and the ceiling of every declaration.

## reference\_envelope

`tai42_kit.llm.checkpoint.envelope.reference_envelope`

```python theme={null}
reference_envelope(ref: CheckpointValueRef) -> dict[str, Any]
```

The `ref` envelope a checkpoint stores in place of the shared value `ref` names.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `ref` | `CheckpointValueRef` | — | — |

## register\_checkpoint\_provider

`tai42_kit.llm.checkpoint.providers.register_checkpoint_provider`

```python theme={null}
register_checkpoint_provider(cls: P) -> P
```

Register `cls` under its `name`; usable as a class decorator.

Raises `TypeError` for a class that is not a `CheckpointProvider`, misses a hook or
declares facts that are not `CheckpointProviderFacts`, and `ValueError` for a malformed
name, a `native_ttl` store without `saver_with_waiting`, or a name
another class holds. The same class registered again is a no-op.

## register\_live\_thread\_filter

`tai42_kit.llm.checkpoint.liveness.register_live_thread_filter`

```python theme={null}
register_live_thread_filter(owner: str, fn: LiveThreadFilter) -> None
```

Register `fn` as `owner`'s live-thread filter; an owner registers once.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `owner` | `str` | — | — |
| `fn` | `LiveThreadFilter` | — | — |

## resolve\_references

`tai42_kit.llm.checkpoint.chunking.resolve_references`

```python theme={null}
async resolve_references(value: Any, encoding: ValueEncoding, fetch: FetchBlobs, thread_id: Any) -> Any
```

`value` with every reference inside it, and inside the values it references, resolved.

The referenced blobs, nested ones included (a reference names them), are fetched in one round trip.
Every place that references a value receives its own object, as if the value were stored there. A
blob the store does not hold, or one whose encoding is not the length its reference records, raises
`CheckpointReferenceError`; nothing is returned partially resolved.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `Any` | — | — |
| `encoding` | `ValueEncoding` | — | — |
| `fetch` | `FetchBlobs` | — | — |
| `thread_id` | `Any` | — | — |

## resolve\_retention

`tai42_kit.llm.checkpoint.retention.resolve_retention`

```python theme={null}
resolve_retention(*, waiting_minutes: int | None = None, finished_minutes: int | None = None) -> ThreadRetention
```

Resolve an owner's declaration against the platform's values.

An unset waiting is the platform's; an unset finished is the platform's finished capped at the
resolved waiting (a finished thread is never kept longer than a waiting one). The resolved
value is bounded where it is built (`ThreadRetention`), which raises
`ThreadRetentionError` for a declaration out of bounds.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `waiting_minutes` | `int \| None` | `None` | — |
| `finished_minutes` | `int \| None` | `None` | — |

## resolve\_tuple

`tai42_kit.llm.checkpoint.chunking.resolve_tuple`

```python theme={null}
async resolve_tuple(tup: CheckpointTuple, encoding: ValueEncoding, fetch: FetchBlobs) -> CheckpointTuple
```

`tup` with every reference in its checkpoint and its pending writes resolved.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `tup` | `CheckpointTuple` | — | — |
| `encoding` | `ValueEncoding` | — | — |
| `fetch` | `FetchBlobs` | — | — |

## shared\_value\_threshold

`tai42_kit.llm.checkpoint.providers.shared_value_threshold`

```python theme={null}
shared_value_threshold(provider: str) -> int | None
```

The encoded size above which `provider` stores a checkpoint sub-value once per thread.

`None` when every value is stored inline. `LLM_PROVIDER_CHECKPOINT_SHARED_VALUES` decides when
it is set; unset, a store that copies channel values into every checkpoint stores them once, and a
store that keeps a channel once per version does not.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `provider` | `str` | — | — |

## stale\_threads\_by\_walk

`tai42_kit.llm.checkpoint.ledger.stale_threads_by_walk`

```python theme={null}
async stale_threads_by_walk(
    saver: BaseCheckpointSaver,
    declared_waiting: Callable[[Sequence[str]], Awaitable[dict[str, int]]],
    *,
    now: datetime,
    default_minutes: int,
) -> list[str]
```

The stale-thread listing of a store without an index of its own, by id.

Reads the newest checkpoint `ts` of every thread, in every namespace, through
`saver.alist(None)`, and compares it with the thread's `declared_waiting` (looked up page by
page), else `default_minutes`, before `now`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `saver` | `BaseCheckpointSaver` | — | — |
| `declared_waiting` | `Callable[[Sequence[str]], Awaitable[dict[str, int]]]` | — | — |
| `now` | `datetime` | — | — |
| `default_minutes` | `int` | — | — |


# Pooled clients (tai42_kit.clients)
Source: https://docs.tai42.ai/reference/python-sdk/kit-clients

Pooled Postgres/Redis clients and connection settings.

Pooled clients + the generic client facade.

Each client subclasses `PooledClient` (per-loop pooling, satisfies the contract
`BaseClient` Protocol) and is reached by class through `client_ctx`. The
driver each impl needs is declared by an extra (`tai42-kit[curl]` /
`[postgres]`); import a driver submodule only when its driver is installed.

## ClientDisconnectedError

`tai42_contract.errors.ClientDisconnectedError`

```python theme={null}
class ClientDisconnectedError(Exception)
```

Raised when a client disconnects unexpectedly and is removed from the cache.

This is not a permanent failure — retrying the operation will cause a fresh
client to be created automatically.

## ClientSettings

`tai42_kit.clients.settings.ClientSettings`

```python theme={null}
class ClientSettings(DefaultNamespaceMixin, TaiBaseSettings)
```

Base a client's settings subclass extends to supply connection kwargs via `client_kwargs()`.

**Attributes**

| Attribute | Type |
| - | - |
| `registry_exclude` | `bool` |

### Members

#### client\_kwargs

`tai42_kit.clients.settings.ClientSettings.client_kwargs`

```python theme={null}
client_kwargs(self) -> dict[str, Any]
```

Connection kwargs passed to the client's `_create` / `current`.

## PooledClient

`tai42_kit.clients.base.PooledClient`

```python theme={null}
class PooledClient
```

A per-event-loop, per-epoch pool for a single driver client of type `T`.

Subclasses implement `_create` and `_close`; callers lease the shared client
through `current`, which rebuilds it after a classified disconnection.

### Members

#### pool\_key

`tai42_kit.clients.base.PooledClient.pool_key`

```python theme={null}
pool_key(self, **kwargs) -> str
```

The pool this client leases for `kwargs`: two calls with equal keys share one pooled client.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kwargs` | — | `{}` | — |

#### current

`tai42_kit.clients.base.PooledClient.current`

```python theme={null}
async current(self, **kwargs) -> AsyncIterator[T]
```

Lease the pooled client for `kwargs`, creating it on first use.

A disconnection inside the body evicts and closes the client and raises
`ClientDisconnectedError`; retry to rebuild it.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kwargs` | — | `{}` | — |

#### close

`tai42_kit.clients.base.PooledClient.close`

```python theme={null}
async close(self, **kwargs) -> None
```

Close and drop the pooled client for `kwargs` in the current epoch, if one is pooled.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kwargs` | — | `{}` | — |

## PostgresConnectionOptions

`tai42_kit.clients.settings.PostgresConnectionOptions`

```python theme={null}
class PostgresConnectionOptions(TaiBaseSettings)
```

Postgres connection behaviour options, with no connection identity.

The base of `PostgresConnectionSettings`, and of a door's own namespace when
the door brings its own DSN and takes only its behaviour from settings.

**Attributes**

| Attribute | Type |
| - | - |
| `registry_exclude` | `bool` |
| `pg_retry_attempts` | `int` |

## PostgresConnectionSettings

`tai42_kit.clients.settings.PostgresConnectionSettings`

```python theme={null}
class PostgresConnectionSettings(ClientSettings, PostgresConnectionOptions)
```

Base Postgres connection settings loaded under a database's `TAI_DATABASE_<NAME>_` prefix.

**Attributes**

| Attribute | Type |
| - | - |
| `registry_exclude` | `bool` |
| `pg_host` | `str \| None` |
| `pg_port` | `int` |
| `pg_db` | `str` |
| `pg_user` | `str` |
| `pg_password` | `SecretStr \| None` |
| `pg_min_connections` | `int` |
| `pg_max_connections` | `int` |
| `pg_connect_timeout` | `int` |
| `pg_statement_timeout_seconds` | `float` |

### Members

#### pg\_dsn

`tai42_kit.clients.settings.PostgresConnectionSettings.pg_dsn`

```python theme={null}
pg_dsn: str
```

Build the libpq DSN from the connection fields; a missing host or password raises a named error.

#### client\_kwargs

`tai42_kit.clients.settings.PostgresConnectionSettings.client_kwargs`

```python theme={null}
client_kwargs(self) -> dict[str, Any]
```

Connection kwargs for the pooled client — JSON-serializable only.

One pool per DSN per loop. `min_size`/`max_size` and `retry_attempts` are
this database's deployment build options, read when the pool is built; a second
settings prefix resolving to the same DSN with different values raises rather than
forking a second pool. `env_prefix` rides along (not identity) so the client can
derive the owning component for the pool name.

## RedisConnectionOptions

`tai42_kit.clients.settings.RedisConnectionOptions`

```python theme={null}
class RedisConnectionOptions(TaiBaseSettings)
```

Redis connection behaviour options, with no connection identity.

The base of `RedisConnectionSettings`, and of a door's own namespace when the
door brings its own connection string and takes only its behaviour from settings.

**Attributes**

| Attribute | Type |
| - | - |
| `registry_exclude` | `bool` |
| `socket_timeout` | `float \| None` |
| `socket_connect_timeout` | `float \| None` |
| `retry_on_timeout` | `bool` |
| `retry_attempts` | `int` |

### Members

#### connection\_options

`tai42_kit.clients.settings.RedisConnectionOptions.connection_options`

```python theme={null}
connection_options(self) -> dict[str, Any]
```

The behaviour knobs that are set, in the kwarg form `redis_connection_options` takes.

## RedisConnectionSettings

`tai42_kit.clients.settings.RedisConnectionSettings`

```python theme={null}
class RedisConnectionSettings(RedisConnectionSettingsBase)
```

Base Redis connection settings with unprefixed field names for a store to subclass with its own prefix.

The decode mode is a setting of the store (`<PREFIX>DECODE_RESPONSES`, default on).

**Attributes**

| Attribute | Type |
| - | - |
| `registry_exclude` | `bool` |
| `decode_responses` | `bool` |

### Members

#### client\_kwargs

`tai42_kit.clients.settings.RedisConnectionSettings.client_kwargs`

```python theme={null}
client_kwargs(self) -> dict[str, Any]
```

The base connection kwargs plus this store's `decode_responses`.

## RedisConnectionSettingsBase

`tai42_kit.clients.settings.RedisConnectionSettingsBase`

```python theme={null}
class RedisConnectionSettingsBase(ClientSettings, RedisConnectionOptions)
```

Redis connection identity and behaviour, with no decode mode.

The base of `RedisConnectionSettings`, and of a component's own connection
when its code fixes the decode mode at each connection: `client_kwargs` then
carries no `decode_responses`, and every caller adds the one its code reads.

**Attributes**

| Attribute | Type |
| - | - |
| `registry_exclude` | `bool` |
| `tai_default_fields` | `Mapping[str, str]` |
| `redis_url` | `str \| None` |
| `redis_max_connections` | `int \| None` |

### Members

#### client\_kwargs

`tai42_kit.clients.settings.RedisConnectionSettingsBase.client_kwargs`

```python theme={null}
client_kwargs(self) -> dict[str, Any]
```

Connection kwargs for the pooled client — JSON-serializable only.

Every option in these kwargs is part of the pool identity: the URL, the decode
mode, `max_connections`, the socket timeouts and the retry options together
select one pooled client per loop. For redis-py the connection options are the
client's contract, so two components resolving to the same URL with different
options get two clients by design — never a conflict. Every value must be
JSON-serializable: `retry_attempts` travels as an int and the kit's materialiser
(`redis_from_url_kwargs`) turns it into a `Retry` object at construction time.

`env_prefix` names this store's component (so the client can name its own env
var when `redis_url` is unset) and is a passenger, not identity — it never
splits a pool. No decode mode is carried here; the caller adds it.

## advance\_client\_epoch

`tai42_kit.clients.base.advance_client_epoch`

```python theme={null}
advance_client_epoch() -> int
```

Advance the process-wide client epoch and return the epoch just retired.

New `current()` leases pool under the new epoch; the retired epoch's pools
stay live until their last lease releases (or `drain_epoch` force-closes
them at a deadline). The same counter stamps cached settings instances.

## client\_ctx

`tai42_kit.clients.facade.client_ctx`

```python theme={null}
client_ctx(
    client_cls: type[PooledClient[T]],
    settings: ClientSettings | None = None,
    *,
    fresh: bool = False,
    **kwargs: Any,
) -> AbstractAsyncContextManager[T]
```

Return an async context manager yielding a connected client for `client_cls`.

Pass either `settings` (its `client_kwargs()` supplies the connection kwargs) or raw
`**kwargs`, never both. `fresh=True` builds a one-shot client outside the pool and closes it
on exit; otherwise the client is pooled and reused per event-loop + connection params.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `client_cls` | `type[PooledClient[T]]` | — | — |
| `settings` | `ClientSettings \| None` | `None` | — |
| `fresh` | `bool` | `False` | — |
| `kwargs` | `Any` | `{}` | — |

## current\_client\_epoch

`tai42_kit.clients.base.current_client_epoch`

```python theme={null}
current_client_epoch() -> int
```

The current client epoch — the value new leases and settings stamps carry.

## drain\_epoch

`tai42_kit.clients.base.drain_epoch`

```python theme={null}
async drain_epoch(epoch: int, deadline: float) -> None
```

Drain and close a retired epoch's client pools for the running loop.

Waits up to `deadline` seconds for every leased client of `epoch` to reach
zero leases (each closes itself on its last release), then force-closes any
that remain regardless of held leases, collecting failures into an
`ExceptionGroup` so none is dropped. Must run on the loop that owns the
pools; the current epoch cannot be drained.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `epoch` | `int` | — | — |
| `deadline` | `float` | — | — |

## shutdown\_all\_clients

`tai42_kit.clients.base.shutdown_all_clients`

```python theme={null}
async shutdown_all_clients() -> None
```

Close every live client pool for the running event loop.

Sweeps every epoch of the per-loop class-keyed cache and closes each pooled
client — process-teardown semantics, independent of leases. Closes are
best-effort — failures are collected and raised together, never silently
dropped.


# Park index and park seams (tai42_kit.interactions)
Source: https://docs.tai42.ai/reference/python-sdk/kit-interactions

The shared park index, the terminal chain notice, and the give-up handler seam a driver that parks registers so an abandoned park's waiter is told.

The durable park index a driver keeps for the runs it parks on an async `ask`.

When a driver parks a run, the platform keeps only the interaction id; the driver reverses it
to its own run through this index. One consumer namespace holds, on one Redis:

* an ENTRY per resume key (an interaction id, or any key the consumer resumes by), carrying the
  consumer's own opaque rebuild payload;
* a BARRIER per parked super-step (a thread's set of asks resolved together): the consumer's
  opaque `expected` map, keyed by member id, the answers buffered so far, and any opaque
  consumer fields;
* a DRIVE LEASE per super-step, so exactly one worker drives a completed barrier, with a
  heartbeat and a token-checked release;
* a RESOLUTION RECORD per resolved super-step and a TOMBSTONE in place of every member entry,
  so a lapped redelivery replays what the first drive returned;
* a RUN-RESOLUTION INDEX per thread (every resolved super-step and its members), so a kill can
  reach every stored outcome of a run;
* a LIVE SET per thread (its super-steps whose barrier is live), so a checkpoint sweep can tell
  a parked thread from an abandoned one.

The module imports no Redis client at import time: the client is reached lazily, so a consumer
whose import graph excludes Redis may import this module. Every Redis error propagates.

## DRIVE\_LEASE\_HEARTBEAT\_SECONDS

`tai42_kit.interactions.park_index.DRIVE_LEASE_HEARTBEAT_SECONDS`

```python theme={null}
DRIVE_LEASE_HEARTBEAT_SECONDS: Final[float] = 20.0
```

## DRIVE\_LEASE\_SECONDS

`tai42_kit.interactions.park_index.DRIVE_LEASE_SECONDS`

```python theme={null}
DRIVE_LEASE_SECONDS: Final[int] = 60
```

## ENTRY\_TTL\_FLOOR\_SECONDS

`tai42_kit.interactions.park_index.ENTRY_TTL_FLOOR_SECONDS`

```python theme={null}
ENTRY_TTL_FLOOR_SECONDS: Final[int] = 30 * 24 * 3600
```

## RESOLVED\_FIELD

`tai42_kit.interactions.park_index.RESOLVED_FIELD`

```python theme={null}
RESOLVED_FIELD: Final[str] = '__park_resolved__'
```

## Barrier

`tai42_kit.interactions._park_types.Barrier`

```python theme={null}
class Barrier
```

A super-step barrier: the consumer's `expected` map, the answers buffered so far, its own fields.

**Attributes**

| Attribute | Type |
| - | - |
| `expected` | `dict[str, Any]` |
| `outputs` | `dict[str, Any]` |
| `fields` | `dict[str, str]` |

## BarrierNotFoundError

`tai42_kit.interactions._park_types.BarrierNotFoundError`

```python theme={null}
class BarrierNotFoundError(ParkIndexError)
```

The super-step barrier an answer converges on is gone (expired or never written).

**Attributes**

| Attribute | Type |
| - | - |
| `thread_id` | — |
| `superstep` | — |

## BufferResult

`tai42_kit.interactions._park_types.BufferResult`

```python theme={null}
class BufferResult
```

Progress after an answer was buffered: answered members, all members, the still-open members in order.

**Attributes**

| Attribute | Type |
| - | - |
| `present` | `int` |
| `total` | `int` |
| `remaining` | `list[str]` |

## DriveInProgressError

`tai42_kit.interactions._park_types.DriveInProgressError`

```python theme={null}
class DriveInProgressError(ParkIndexError)
```

Another worker holds the super-step's drive lease.

Raised (never a benign return) so the platform keeps the caller's durable retry ticket and
redelivers until the live drive completes or its lease expires.

**Attributes**

| Attribute | Type |
| - | - |
| `thread_id` | — |
| `superstep` | — |

## DriveLease

`tai42_kit.interactions.park_index.DriveLease`

```python theme={null}
class DriveLease
```

A super-step's drive lease: `SET NX EX` to win it, a heartbeat while held, a token-checked release.

Win it by entering (`async with`) or `acquire`; leave it by exiting or `close`,
which stops the heartbeat and releases it unless `ParkIndex.finalize` consumed it.

**Attributes**

| Attribute | Type |
| - | - |
| `index` | — |
| `thread_id` | — |
| `superstep` | — |
| `token` | — |
| `acquired` | — |
| `consumed` | — |
| `lost` | — |
| `closed` | — |

### Members

#### acquire

`tai42_kit.interactions.park_index.DriveLease.acquire`

```python theme={null}
async acquire(self) -> DriveLease
```

Win the lease and start its heartbeat.

#### holds

`tai42_kit.interactions.park_index.DriveLease.holds`

```python theme={null}
async holds(self) -> bool
```

Whether this lease's token still holds the super-step right now.

#### release

`tai42_kit.interactions.park_index.DriveLease.release`

```python theme={null}
async release(self) -> None
```

Drop the lease if this token still holds it (a reclaimer's lease is never dropped).

#### close

`tai42_kit.interactions.park_index.DriveLease.close`

```python theme={null}
async close(self) -> None
```

Stop the heartbeat and release the lease once; a consumed lease is left as finalize left it.

A cancel of the calling task delivered while the heartbeat stops propagates, after the release.

#### mark\_consumed

`tai42_kit.interactions.park_index.DriveLease.mark_consumed`

```python theme={null}
async mark_consumed(self) -> None
```

Record that a finalize dropped the lease key; stops the heartbeat so no renew reports it lost.

## LeaseLostError

`tai42_kit.interactions._park_types.LeaseLostError`

```python theme={null}
class LeaseLostError(ParkIndexError)
```

The caller no longer holds the drive lease its write is guarded by; another writer owns the super-step.

**Attributes**

| Attribute | Type |
| - | - |
| `thread_id` | — |
| `superstep` | — |

## ParkIndex

`tai42_kit.interactions.park_index.ParkIndex`

```python theme={null}
class ParkIndex
```

One consumer's park index under its own key namespace on its own Redis.

**Attributes**

| Attribute | Type |
| - | - |
| `namespace` | — |

### Members

#### entry\_key

`tai42_kit.interactions.park_index.ParkIndex.entry_key`

```python theme={null}
entry_key(self, entry_id: str) -> str
```

The key of the entry stored for `entry_id`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `entry_id` | `str` | — | — |

#### barrier\_key

`tai42_kit.interactions.park_index.ParkIndex.barrier_key`

```python theme={null}
barrier_key(self, thread_id: str, superstep: str) -> str
```

The key of a super-step's barrier hash.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |
| `superstep` | `str` | — | — |

#### lease\_key

`tai42_kit.interactions.park_index.ParkIndex.lease_key`

```python theme={null}
lease_key(self, thread_id: str, superstep: str) -> str
```

The key of a super-step's drive lease.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |
| `superstep` | `str` | — | — |

#### resolution\_key

`tai42_kit.interactions.park_index.ParkIndex.resolution_key`

```python theme={null}
resolution_key(self, thread_id: str, superstep: str) -> str
```

The key of a resolved super-step's resolution record.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |
| `superstep` | `str` | — | — |

#### run\_resolutions\_key

`tai42_kit.interactions.park_index.ParkIndex.run_resolutions_key`

```python theme={null}
run_resolutions_key(self, thread_id: str) -> str
```

The key of a thread's run-resolution index.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |

#### live\_set\_key

`tai42_kit.interactions.park_index.ParkIndex.live_set_key`

```python theme={null}
live_set_key(self, thread_id: str) -> str
```

The key of a thread's set of super-steps whose barrier is live.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |

#### persist

`tai42_kit.interactions.park_index.ParkIndex.persist`

```python theme={null}
async persist(
    self,
    *,
    thread_id: str,
    superstep: str,
    entries: Mapping[str, Mapping[str, Any]],
    expected: Mapping[str, Any],
    barrier_fields: Mapping[str, str] | None = None,
    entry_ttl: Mapping[str, int],
    barrier_ttl: int,
) -> None
```

Write a parked super-step's entries, its barrier and its live-set membership, all or nothing.

Each entry is written whole under its own TTL; the barrier holds `expected` (keyed by
member id) and `barrier_fields`; the thread's live set lasts as long as its longest-lived
barrier.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |
| `superstep` | `str` | — | — |
| `entries` | `Mapping[str, Mapping[str, Any]]` | — | — |
| `expected` | `Mapping[str, Any]` | — | — |
| `barrier_fields` | `Mapping[str, str] \| None` | `None` | — |
| `entry_ttl` | `Mapping[str, int]` | — | — |
| `barrier_ttl` | `int` | — | — |

#### threads\_with\_live\_barriers

`tai42_kit.interactions.park_index.ParkIndex.threads_with_live_barriers`

```python theme={null}
async threads_with_live_barriers(self, thread_ids: Sequence[str]) -> set[str]
```

The subset of `thread_ids` with at least one live barrier.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_ids` | `Sequence[str]` | — | — |

#### read\_entry

`tai42_kit.interactions.park_index.ParkIndex.read_entry`

```python theme={null}
async read_entry(self, entry_id: str) -> dict[str, Any] | None
```

The entry or tombstone stored for `entry_id`, or `None` when there is none.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `entry_id` | `str` | — | — |

#### tombstone\_kind

`tai42_kit.interactions.park_index.ParkIndex.tombstone_kind`

```python theme={null}
tombstone_kind(entry: Mapping[str, Any]) -> TombstoneKind
```

Whether a read entry is a live entry, a resolved tombstone, or a detached tombstone.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `entry` | `Mapping[str, Any]` | — | — |

#### tombstone\_coordinates

`tai42_kit.interactions.park_index.ParkIndex.tombstone_coordinates`

```python theme={null}
tombstone_coordinates(entry: Mapping[str, Any]) -> tuple[str, str]
```

The `(thread_id, superstep)` a resolved tombstone points at.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `entry` | `Mapping[str, Any]` | — | — |

#### read\_tombstone\_resolution

`tai42_kit.interactions.park_index.ParkIndex.read_tombstone_resolution`

```python theme={null}
async read_tombstone_resolution(self, entry: Mapping[str, Any]) -> ResolutionRecord | None
```

The record a tombstone resolves to: the stored record of a resolved one, `None` for a detached one.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `entry` | `Mapping[str, Any]` | — | — |

#### read\_barrier

`tai42_kit.interactions.park_index.ParkIndex.read_barrier`

```python theme={null}
async read_barrier(self, thread_id: str, superstep: str) -> Barrier | None
```

A super-step's barrier, or `None` when it is gone; buffered answers are decoded.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |
| `superstep` | `str` | — | — |

#### set\_barrier\_fields

`tai42_kit.interactions.park_index.ParkIndex.set_barrier_fields`

```python theme={null}
async set_barrier_fields(self, thread_id: str, superstep: str, fields: Mapping[str, str]) -> bool
```

Write consumer fields onto a live barrier; `False` (nothing written) when the barrier is gone.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |
| `superstep` | `str` | — | — |
| `fields` | `Mapping[str, str]` | — | — |

#### buffer

`tai42_kit.interactions.park_index.ParkIndex.buffer`

```python theme={null}
async buffer(self, thread_id: str, superstep: str, member_id: str, answer: Any) -> BufferResult
```

Buffer one member's answer into its barrier, idempotently, and report progress.

A redelivered answer for a member already answered keeps the first one.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |
| `superstep` | `str` | — | — |
| `member_id` | `str` | — | — |
| `answer` | `Any` | — | — |

#### claim

`tai42_kit.interactions.park_index.ParkIndex.claim`

```python theme={null}
claim(self, thread_id: str, superstep: str) -> DriveLease
```

A drive lease on a super-step, won by entering it (`async with` or `DriveLease.acquire`).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |
| `superstep` | `str` | — | — |

#### finalize

`tai42_kit.interactions.park_index.ParkIndex.finalize`

```python theme={null}
async finalize(
    self,
    lease: DriveLease,
    *,
    member_ids: Sequence[str],
    resolution: Resolution,
    value: Any,
) -> None
```

Resolve a super-step under `lease`: tombstone its members, store its record, drop its barrier and lease.

One guarded step: it lands only while `lease` still holds the super-step, and it also
records the super-step in its thread's run-resolution index and leaves the thread's live
set. On success the lease is consumed and its heartbeat stopped.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `lease` | `DriveLease` | — | — |
| `member_ids` | `Sequence[str]` | — | — |
| `resolution` | `Resolution` | — | — |
| `value` | `Any` | — | — |

#### read\_resolution

`tai42_kit.interactions.park_index.ParkIndex.read_resolution`

```python theme={null}
async read_resolution(self, thread_id: str, superstep: str) -> ResolutionRecord | None
```

A resolved super-step's record, or `None` when it has none.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |
| `superstep` | `str` | — | — |

#### run\_resolutions

`tai42_kit.interactions.park_index.ParkIndex.run_resolutions`

```python theme={null}
async run_resolutions(self, thread_id: str) -> dict[str, list[str]]
```

Every resolved super-step of a thread with its members, `{}` when none.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |

#### drop\_run\_resolutions

`tai42_kit.interactions.park_index.ParkIndex.drop_run_resolutions`

```python theme={null}
async drop_run_resolutions(self, thread_id: str, *, keep: str | None = None) -> None
```

Drop every resolved super-step of a thread but `keep` (member tombstones and record), then its index.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |
| `keep` | `str \| None` | `None` | — |

#### drop\_resolution

`tai42_kit.interactions.park_index.ParkIndex.drop_resolution`

```python theme={null}
async drop_resolution(self, thread_id: str, superstep: str, *, member_ids: Iterable[str] = ()) -> list[str]
```

Drop one resolved super-step: its record, its members' tombstones (and `member_ids`), its index member.

Returns the sorted member ids whose tombstones it dropped.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `thread_id` | `str` | — | — |
| `superstep` | `str` | — | — |
| `member_ids` | `Iterable[str]` | `()` | — |

#### detach

`tai42_kit.interactions.park_index.ParkIndex.detach`

```python theme={null}
async detach(
    self,
    entry_ids: Sequence[str],
    *,
    expiry_ats: Iterable[datetime | None] = (),
) -> None
```

Tombstone keys that were claimed but never parked on, never overwriting an existing key.

Each detached tombstone lives the held step's park-entry life — the entry floor, extended to
outlast the LATEST of `expiry_ats` by the redelivery horizon (`barrier_ttl_seconds`) — so a run
whose chain was detached but which still fires the key until its own deadline finds the
tombstone and its fire lands transparently, not a key the tombstone already dropped. A
re-park grows it through `extend_horizon`. With no deadline the floor alone applies.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `entry_ids` | `Sequence[str]` | — | — |
| `expiry_ats` | `Iterable[datetime \| None]` | `()` | — |

#### extend\_horizon

`tai42_kit.interactions.park_index.ParkIndex.extend_horizon`

```python theme={null}
async extend_horizon(self, entry_id: str, expiry_at: datetime | None) -> bool
```

Grow the TTLs backing `entry_id` to outlast `expiry_at`; never shrink one.

A LIVE entry grows its own, its barrier's and its thread's live set's TTLs. A DETACHED
tombstone (a chain released or claimed but never parked on, whose held run still fires the
key until its own deadline) has no barrier and no live set, so only its own TTL grows — so a
re-park notice carries the tombstone out to the run's new deadline. Returns `False` when no
live entry or detached tombstone backs `entry_id` (absent, or a resolved tombstone, which
stays at its resolution record's life).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `entry_id` | `str` | — | — |
| `expiry_at` | `datetime \| None` | — | — |

## ParkIndexCorruptError

`tai42_kit.interactions._park_types.ParkIndexCorruptError`

```python theme={null}
class ParkIndexCorruptError(ParkIndexError)
```

A stored park index value does not have the shape the index writes.

## ParkIndexError

`tai42_kit.interactions._park_types.ParkIndexError`

```python theme={null}
class ParkIndexError(RuntimeError)
```

Base of every park index failure.

## ParkValueCodecError

`tai42_kit.interactions._park_types.ParkValueCodecError`

```python theme={null}
class ParkValueCodecError(ParkIndexError)
```

A value cannot be stored in, or read back from, the park index.

## Resolution

`tai42_kit.interactions._park_types.Resolution`

```python theme={null}
Resolution = Literal['terminal', 'suspended', 'aborted']
```

## ResolutionMissingError

`tai42_kit.interactions._park_types.ResolutionMissingError`

```python theme={null}
class ResolutionMissingError(ParkIndexError)
```

A resolved tombstone points at a resolution record that is gone.

**Attributes**

| Attribute | Type |
| - | - |
| `thread_id` | — |
| `superstep` | — |

## ResolutionRecord

`tai42_kit.interactions._park_types.ResolutionRecord`

```python theme={null}
class ResolutionRecord
```

What a resolved super-step stored: how it resolved and the value a redelivery replays.

**Attributes**

| Attribute | Type |
| - | - |
| `resolution` | `Resolution` |
| `value` | `Any` |

## SuperstepAlreadyResolvedError

`tai42_kit.interactions._park_types.SuperstepAlreadyResolvedError`

```python theme={null}
class SuperstepAlreadyResolvedError(ParkIndexError)
```

The barrier was finalized while an answer was being buffered into it; the super-step already resolved.

**Attributes**

| Attribute | Type |
| - | - |
| `thread_id` | — |
| `superstep` | — |

## TombstoneKind

`tai42_kit.interactions.park_index.TombstoneKind`

```python theme={null}
TombstoneKind = Literal['live', 'resolved', 'detached']
```

## barrier\_ttl\_seconds

`tai42_kit.interactions.park_index.barrier_ttl_seconds`

```python theme={null}
barrier_ttl_seconds(expiries: Iterable[datetime | None]) -> int
```

A barrier's TTL: the entry TTL (`entry_ttl_seconds`) of the LATEST deadline it coordinates.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `expiries` | `Iterable[datetime \| None]` | — | — |

## decode\_value

`tai42_kit.interactions._park_types.decode_value`

```python theme={null}
decode_value(encoded: Any) -> Any
```

Rebuild a value from its tagged mapping (`encode_value`'s inverse).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `encoded` | `Any` | — | — |

## encode\_value

`tai42_kit.interactions._park_types.encode_value`

```python theme={null}
encode_value(value: Any) -> dict[str, Any]
```

Encode a resolution value or a buffered answer as a tagged JSON mapping.

A contract outcome type keeps its type across the store; any other pydantic model is refused,
and a plain value must be JSON-serializable.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `Any` | — | — |

## entry\_ttl\_seconds

`tai42_kit.interactions.park_index.entry_ttl_seconds`

```python theme={null}
entry_ttl_seconds(expiry_at: datetime | None) -> int
```

An entry's TTL: the floor, extended to outlast its ask's deadline by the redelivery horizon.

The platform keeps a park with a deadline resolvable for the redelivery horizon past that
deadline, so a late expiry reaper still resolves it; the entry it reaches lives at least as
long, by the same rule: the whole seconds remaining to the deadline plus the horizon.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `expiry_at` | `datetime \| None` | — | — |

## resolution\_ttl\_seconds

`tai42_kit.interactions.park_index.resolution_ttl_seconds`

```python theme={null}
resolution_ttl_seconds() -> int
```

The TTL of a resolution record and its tombstones: twice the platform's redelivery horizon.

They must outlive the last redelivery the reaper can fire, plus reaper-cycle and clock-skew
margin, and no longer (they hold a run's outcome).

## superstep\_id

`tai42_kit.interactions.park_index.superstep_id`

```python theme={null}
superstep_id(member_ids: Iterable[str]) -> str
```

A deterministic super-step id: a sha256 over the sorted member ids, insensitive to their order.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `member_ids` | `Iterable[str]` | — | — |

Park adoption and the chained-call notices: which park a run records for a returned sentinel, and what it fires.

A park belongs to exactly ONE resume continuation — the one bound when it was raised — and
carries that owner BOTH on its sentinel and on its wire-form marker. `assert_park_adoptable`
is the guard every seam that turns a park into the CALLER's own suspended state applies: the
object seams that adopt a returned sentinel, and the CLAIM point where a driver records resume
state against a marker read off a serialized tool result. So a nested run's park is never adopted
by its caller (which would then wait for a resume fired only at the nested run).

The owner is the continuation NAME, not a per-run token, because that is the whole of what the
platform dispatches: the name is what the interaction stores and what a later answer invokes, so
a scoped owner would have to be unscoped again before dispatch and would fork the meaning of the
resume binding. Name equality alone is not what makes the guard sound — two runs of the same
driver share a name — the `None` rule is: a park crossing a nested RUN's face carries no owner
at all, so a same-named sibling is refused on that, never on a name comparison happening to
differ.

Refusing is not the only answer to a park this caller does not own. `resolve_park_adoption`
is the OBJECT seams' form of the guard, and it answers adopt-your-own or CHAIN: a nested dispatch
a CHAIN routing (`ChainedResume`) was bound around parks on
the nested CALL — a key of its own, owned by its own resume continuation, recorded in the open
ledger with the held step's deadline so a drive that never parks on it detaches it sized past that
deadline — while the nested run keeps its park and its resume, and its terminal re-enters the
caller through the routing's delivery tool. A dispatch nothing chained still gets the loud refusal.
The CLAIM point cannot chain: a park reaching it as content belongs to no dispatch it could
attribute the call to, so there it is adopt-or-refuse.

Every driver builds the chain fires here too — `repark_notice` when a chained run re-parks,
`terminal_chain_notice` at its terminal — so each payload has one shape.

## PARK\_SUPERSEDED\_OUTCOME

`tai42_kit.interactions.park_adoption.PARK_SUPERSEDED_OUTCOME`

```python theme={null}
PARK_SUPERSEDED_OUTCOME: Final[dict[str, str]] = {'status': 'superseded', 'reason': 'the run was resumed inline by another caller, which now owns its outcome'}
```

## assert\_park\_adoptable

`tai42_kit.interactions.park_adoption.assert_park_adoptable`

```python theme={null}
assert_park_adoptable(resume_owner: str | None, *, interaction_id: str, tool_name: str) -> None
```

Guard the seam where a caller ADOPTS a park as its OWN.

Applies to a returned sentinel or the wire-form marker, where the caller records resume
state of its own against that interaction.

`resume_owner` is the park's `SuspendedInteraction.resume_owner`, and the guard's
role is a NESTING DISCRIMINATOR, not an authenticity token: it separates a park a run raised
UNDER ITS OWN resume binding (adoptable) from one that crossed a NESTED run's face on the way
up (not — that nested run is resumed on its own path, so adopting it would wait for a resume
fired elsewhere and hang forever). A park a run raises for itself carries the continuation it
was raised under; a park crossing a nested RUN's face carries no owner at all. So the guard is
sound on the `None` rule, not on name equality: a same-named sibling run is refused because
its park reaches here ownerless, never because two names happened to differ.

`None` is never adoptable, by ANY caller: it is the signal a park crossed a nested run's
face (or is content shaped to look like a park), neither of which this caller may turn into
its own suspended state. An unbound caller is refused too — it has no continuation the
platform could fire, so a park it claimed could only hang. A BLANK owner reads as no owner:
it names no registered tool the platform could dispatch.

This name check does NOT authenticate the marker against any store — the resume owner is a
public continuation name, so a well-formed marker naming the bound continuation is treated as
adoptable here. Structural validation of the marker shape lives in
`read_suspended_interaction_marker`;
store-authoritative existence is a separate concern the claim seams that hold a store handle
apply.

Raises `NestedParkOwnershipError` BEFORE any state of the
caller's own is recorded, so the owning run's park stays untouched and resumable on its own
path. A seam holding the sentinel a nested CALL returned applies `resolve_park_adoption`
instead, which answers this same question but can also CHAIN the call rather than refuse it.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `resume_owner` | `str \| None` | — | — |
| `interaction_id` | `str` | — | — |
| `tool_name` | `str` | — | — |

## attach\_chained\_park

`tai42_kit.interactions.park_adoption.attach_chained_park`

```python theme={null}
attach_chained_park(key: str) -> None
```

Mark a claimed chained `key` as ATTACHED so the ledger drops it.

The driver recorded a park on it, so it is no longer a dead chain. A no-op when no
`chained_park_claims` ledger is open, or when the key was never claimed inside it.

**Parameters**

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

## chained\_park\_claims

`tai42_kit.interactions.park_adoption.chained_park_claims`

```python theme={null}
chained_park_claims(claims: dict[str, datetime | None] | None = None) -> Generator[dict[str, datetime | None]]
```

Bind the per-drive ledger of chained keys `resolve_park_adoption` CLAIMED, yield the dict.

A driver opens one around each drive so it can tell, when the drive stops, which chained
calls it actually parked on: it drops each key it persists, and whatever REMAINS is a
claim the drive never turned into a park (the run errored, or moved on without parking).
Those are dead chains — the nested run will still fire its terminal at them — so the
driver detaches them rather than leaving the fire to hunt a park that will never exist.

The ledger maps each claimed chained key to the HELD step's deadline — the `expiry_at`
`resolve_park_adoption` recorded for it, `None` when the held step carried none — so a
driver sizes the dead-chain detach past that deadline (`expiry_ats=claims.values()`) and the
tombstone outlasts the run that still fires the key until its own deadline.

The yielded dict is mutated in place, so a claim recorded inside a task the drive spawns
(every nested dispatch runs in a child context) is visible to the opener.

`claims` lets a caller pass an EXISTING ledger to re-bind rather than a fresh one. A driver
that binds per drive-step — the resume binding cannot span a generator's yields, so it is
re-entered around each `__anext__` — owns one accumulating ledger for the whole drive and
re-binds it here each step, so a claim recorded in an early step survives to the reconcile
at the end. Omit it (the default) to open a fresh ledger for the whole drive at once.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `claims` | `dict[str, datetime \| None] \| None` | `None` | — |

## is\_chained\_park\_key

`tai42_kit.interactions.park_adoption.is_chained_park_key`

```python theme={null}
is_chained_park_key(key: str) -> bool
```

Whether `key` names a chained CALL rather than a platform interaction.

The discriminator a driver indexing both key kinds reads before applying any policy that
only makes sense for one of them (a chained key has no interaction, so nothing expires
it and no answer is ever delivered against it directly).

**Parameters**

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

## new\_chained\_park\_key

`tai42_kit.interactions.park_adoption.new_chained_park_key`

```python theme={null}
new_chained_park_key() -> str
```

Mint a fresh chained resume key for ONE nested dispatch.

Namespaced and unique per call, so two nested calls never converge on one key.

## repark\_notice

`tai42_kit.interactions.park_adoption.repark_notice`

```python theme={null}
repark_notice(expiry_at: datetime | None) -> tuple[str, dict[str, Any]] | None
```

The `(tool, payload)` fired when a park is raised under a bound chain routing.

Returns `None` when no chain routing is bound around the current dispatch.

A chained caller's own suspension horizon is INHERITED from the nested run's current ask,
so when that run re-parks on a new ask the caller's horizon must move with it. The notice
is that signal: the routing's `delivery_tool` paired with `{CHAINED_PARK_TOKEN_KEY:
routing.chain_key, "expiry_at": <iso>, "status": PARK_COMPLETION_REPARKED}` — the one
non-terminal status, carrying the new deadline in place of a result and the chain key the
delivery tool reverses back to the caller's park. It resolves nothing; the completion still
fires later under a terminal status.

Only a bound chain routing is notified, so no other delivery tool ever sees this fire.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `expiry_at` | `datetime \| None` | — | — |

## resolve\_park\_adoption

`tai42_kit.interactions.park_adoption.resolve_park_adoption`

```python theme={null}
resolve_park_adoption(
    resume_owner: str | None,
    *,
    interaction_id: str,
    tool_name: str,
    expiry_at: datetime | None,
) -> tuple[str, str | None]
```

The park THIS run records for a returned park sentinel — ADOPT-your-own, or CHAIN.

Returned as the `(key, resume_owner)` its own park is keyed and owned by.

The OBJECT seams' form of `assert_park_adoptable`, for a seam holding the sentinel a
nested call returned. Three outcomes, in this order:

* the park is adoptable here (raised under the continuation bound HERE) — it is this run's
  own park, returned unchanged, and the platform resumes it directly;
* otherwise, if this dispatch was CHAINED (a chain routing was bound around it,
  `get_chained_resume`), the run parks on the chained resume
  KEY instead, owned by this run's OWN resume continuation — because that park is genuinely
  this run's: it waits on the CALL, while the nested run keeps its own park and its own resume
  and re-enters here through the chain's delivery tool when it terminates. The key is recorded
  in the open `chained_park_claims` ledger against `expiry_at` — the held step's
  deadline — so a drive that never turns the claim into a park detaches it sized past that
  deadline;
* otherwise `NestedParkOwnershipError`, exactly as
  `assert_park_adoptable` raises it: waiting on a foreign park with nothing chained would
  leave this run suspended behind a resume fired only at the nested run.

`expiry_at` is the returned sentinel's
`expiry_at` — the held step's deadline,
the latest of its open asks — carried so the ledger can size a dead-chain detach past it. It is
recorded only on the CHAIN outcome; an adopted own park needs no chain claim and ignores it.

Never returns a foreign interaction id, and never returns a key owned by anything but the
continuation bound here — so the claim point downstream reaches the same verdict.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `resume_owner` | `str \| None` | — | — |
| `interaction_id` | `str` | — | — |
| `tool_name` | `str` | — | — |
| `expiry_at` | `datetime \| None` | — | — |

## supersede\_chain\_notice

`tai42_kit.interactions.park_adoption.supersede_chain_notice`

```python theme={null}
supersede_chain_notice(routing: ChainedResume) -> tuple[str, dict[str, Any]]
```

The `(delivery tool, payload)` that ends a chain routing a later inline resumer superseded.

A run resumed inline by a caller that chains it with a routing of its own takes the call over:
the drive runs under the resumer's routing and its terminal reaches the resumer, so the routing
the park had captured no longer fires at this run's terminal. This notice ends that superseded
routing `failed` with `PARK_SUPERSEDED_OUTCOME`, so a caller still parked on it fails
loudly through its own error path instead of waiting on a key nothing will fire. The drive still
fires the resumer's routing with the real terminal through `terminal_chain_notice`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `routing` | `ChainedResume` | — | — |

## terminal\_chain\_notice

`tai42_kit.interactions.park_adoption.terminal_chain_notice`

```python theme={null}
terminal_chain_notice(routing: ChainedResume, result: Any) -> tuple[str, dict[str, Any]]
```

The `(delivery tool, payload)` a run's terminal fires along its captured chain routing.

A `RunFailed` result is a failed terminal: its opaque
`outcome` rides as the `result` under the `failed` status. Any other result is a
success, carried whole. The payload keys are exactly the chain key, `result` and
`status`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `routing` | `ChainedResume` | — | — |
| `result` | `Any` | — | — |

The give-up handler seam: the driver that parked a run tells its waiter when the platform abandons the park.

When the platform gives up redelivering an answered park (its continuation-due record outlived
the redelivery horizon), the waiter to tell is the one the parking DRIVER captured for that
park. The platform names the interaction only; each driver that parks registers one handler,
reads its own record of that interaction, runs its own failed-terminal epilogue and returns the
outermost outcome for the platform to deliver to the run's address. A handler returns `None`
for an interaction that is not its park.

## ParkGiveUpHandler

`tai42_kit.interactions.park_giveup.ParkGiveUpHandler`

```python theme={null}
ParkGiveUpHandler: TypeAlias = Callable[[str, Mapping[str, Any]], Awaitable[ParkGiveUpOutcome | None]]
```

## ParkGiveUpOutcome

`tai42_kit.interactions.park_giveup.ParkGiveUpOutcome`

```python theme={null}
class ParkGiveUpOutcome(NamedTuple)
```

The outermost outcome of a run whose abandoned park its driver gave up, for the platform to deliver.

**Attributes**

| Attribute | Type |
| - | - |
| `result` | `Any` |

## fire\_park\_giveup

`tai42_kit.interactions.park_giveup.fire_park_giveup`

```python theme={null}
async fire_park_giveup(interaction_id: str, failed_outcome: Mapping[str, Any]) -> ParkGiveUpOutcome | None
```

Ask each registered handler in turn to give up `interaction_id`'s park; return the first one's outcome.

A handler that owns the park returns its outcome and later handlers are not called; `None`
when no handler owns it. A handler's raise propagates.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `interaction_id` | `str` | — | — |
| `failed_outcome` | `Mapping[str, Any]` | — | — |

## register\_park\_giveup\_handler

`tai42_kit.interactions.park_giveup.register_park_giveup_handler`

```python theme={null}
register_park_giveup_handler(handler: ParkGiveUpHandler) -> None
```

Register a driver's give-up handler; handlers run in registration order. A driver registers once at import.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `handler` | `ParkGiveUpHandler` | — | — |


# LLM factories and the classifier contract (tai42_kit.llm)
Source: https://docs.tai42.ai/reference/python-sdk/kit-llm

LLM, embedding, checkpoint, and store factories, plus the classifier contract models.

LLM provider factories + the LangGraph checkpoint/store registries.

The chat-model, embedding, and classifier factories cache per `(provider,
kwargs)` and import their langchain provider package lazily inside the build;
the registry accessors return the running event loop's singletons that pool
checkpoint/store connection resources. Importing this package pulls
`langchain_core` / `langgraph` — that is the opt-in boundary (the
`tai42_kit` top level stays vendor-free).

## InvalidRunTraceError

`tai42_kit.llm.run_trace.InvalidRunTraceError`

```python theme={null}
class InvalidRunTraceError(ValueError)
```

A run's config names an explicit trace id or parent anchor that no monitoring writer can record under.

The caller's input is refused before the run starts, naming the configurable key and the value it carried.

## MonitoringCallbackHandler

`tai42_kit.llm.monitoring_callbacks.MonitoringCallbackHandler`

```python theme={null}
class MonitoringCallbackHandler(BaseCallbackHandler)
```

Records one bound run's LangChain runs through `writer` under `trace_context`.

`grouping_nodes` names the framework nodes (`langgraph_node`) that hold steps rather
than being one; their chain records carry `StepRole.GROUPING`. `chain_payloads`
selects how chain runs record their input/output (see the module docstring).

**Attributes**

| Attribute | Type |
| - | - |
| `run_inline` | — |
| `writer` | — |
| `trace_context` | — |
| `grouping_nodes` | — |
| `chain_payloads` | `ChainPayloads` |

### Members

#### on\_chain\_start

`tai42_kit.llm.monitoring_callbacks.MonitoringCallbackHandler.on_chain_start`

```python theme={null}
on_chain_start(
    self,
    serialized: dict[str, Any] | None,
    inputs: Any,
    *,
    run_id: UUID,
    parent_run_id: UUID | None = None,
    tags: list[str] | None = None,
    metadata: dict[str, Any] | None = None,
    **kwargs: Any,
) -> None
```

Open the chain run's span and record its input payload.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `serialized` | `dict[str, Any] \| None` | — | — |
| `inputs` | `Any` | — | — |
| `run_id` | `UUID` | — | — |
| `parent_run_id` | `UUID \| None` | `None` | — |
| `tags` | `list[str] \| None` | `None` | — |
| `metadata` | `dict[str, Any] \| None` | `None` | — |
| `kwargs` | `Any` | `{}` | — |

#### on\_chain\_end

`tai42_kit.llm.monitoring_callbacks.MonitoringCallbackHandler.on_chain_end`

```python theme={null}
on_chain_end(
    self,
    outputs: Any,
    *,
    run_id: UUID,
    parent_run_id: UUID | None = None,
    **kwargs: Any,
) -> None
```

Record the chain run's output payload and end its span.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `outputs` | `Any` | — | — |
| `run_id` | `UUID` | — | — |
| `parent_run_id` | `UUID \| None` | `None` | — |
| `kwargs` | `Any` | `{}` | — |

#### on\_chain\_error

`tai42_kit.llm.monitoring_callbacks.MonitoringCallbackHandler.on_chain_error`

```python theme={null}
on_chain_error(
    self,
    error: BaseException,
    *,
    run_id: UUID,
    parent_run_id: UUID | None = None,
    **kwargs: Any,
) -> None
```

End the chain run's span: an interrupt as interrupted, any other error at ERROR.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `error` | `BaseException` | — | — |
| `run_id` | `UUID` | — | — |
| `parent_run_id` | `UUID \| None` | `None` | — |
| `kwargs` | `Any` | `{}` | — |

#### on\_chat\_model\_start

`tai42_kit.llm.monitoring_callbacks.MonitoringCallbackHandler.on_chat_model_start`

```python theme={null}
on_chat_model_start(
    self,
    serialized: dict[str, Any] | None,
    messages: list[list[BaseMessage]],
    *,
    run_id: UUID,
    parent_run_id: UUID | None = None,
    **kwargs: Any,
) -> None
```

Open the model run's span with its input messages in full.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `serialized` | `dict[str, Any] \| None` | — | — |
| `messages` | `list[list[BaseMessage]]` | — | — |
| `run_id` | `UUID` | — | — |
| `parent_run_id` | `UUID \| None` | `None` | — |
| `kwargs` | `Any` | `{}` | — |

#### on\_llm\_start

`tai42_kit.llm.monitoring_callbacks.MonitoringCallbackHandler.on_llm_start`

```python theme={null}
on_llm_start(
    self,
    serialized: dict[str, Any] | None,
    prompts: list[str],
    *,
    run_id: UUID,
    parent_run_id: UUID | None = None,
    **kwargs: Any,
) -> None
```

Open the completion run's span with each prompt as one user message.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `serialized` | `dict[str, Any] \| None` | — | — |
| `prompts` | `list[str]` | — | — |
| `run_id` | `UUID` | — | — |
| `parent_run_id` | `UUID \| None` | `None` | — |
| `kwargs` | `Any` | `{}` | — |

#### on\_llm\_end

`tai42_kit.llm.monitoring_callbacks.MonitoringCallbackHandler.on_llm_end`

```python theme={null}
on_llm_end(
    self,
    response: LLMResult,
    *,
    run_id: UUID,
    parent_run_id: UUID | None = None,
    **kwargs: Any,
) -> None
```

Record the generated messages in full, the usage and the generated message's full record.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `response` | `LLMResult` | — | — |
| `run_id` | `UUID` | — | — |
| `parent_run_id` | `UUID \| None` | `None` | — |
| `kwargs` | `Any` | `{}` | — |

#### on\_llm\_error

`tai42_kit.llm.monitoring_callbacks.MonitoringCallbackHandler.on_llm_error`

```python theme={null}
on_llm_error(
    self,
    error: BaseException,
    *,
    run_id: UUID,
    parent_run_id: UUID | None = None,
    **kwargs: Any,
) -> None
```

End the model run's span at ERROR.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `error` | `BaseException` | — | — |
| `run_id` | `UUID` | — | — |
| `parent_run_id` | `UUID \| None` | `None` | — |
| `kwargs` | `Any` | `{}` | — |

#### on\_tool\_start

`tai42_kit.llm.monitoring_callbacks.MonitoringCallbackHandler.on_tool_start`

```python theme={null}
on_tool_start(
    self,
    serialized: dict[str, Any] | None,
    input_str: str,
    *,
    run_id: UUID,
    parent_run_id: UUID | None = None,
    inputs: dict[str, Any] | None = None,
    **kwargs: Any,
) -> None
```

Open the tool run's span with its arguments in full.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `serialized` | `dict[str, Any] \| None` | — | — |
| `input_str` | `str` | — | — |
| `run_id` | `UUID` | — | — |
| `parent_run_id` | `UUID \| None` | `None` | — |
| `inputs` | `dict[str, Any] \| None` | `None` | — |
| `kwargs` | `Any` | `{}` | — |

#### on\_tool\_end

`tai42_kit.llm.monitoring_callbacks.MonitoringCallbackHandler.on_tool_end`

```python theme={null}
on_tool_end(
    self,
    output: Any,
    *,
    run_id: UUID,
    parent_run_id: UUID | None = None,
    **kwargs: Any,
) -> None
```

Record the tool's result in full and end its span.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `output` | `Any` | — | — |
| `run_id` | `UUID` | — | — |
| `parent_run_id` | `UUID \| None` | `None` | — |
| `kwargs` | `Any` | `{}` | — |

#### on\_tool\_error

`tai42_kit.llm.monitoring_callbacks.MonitoringCallbackHandler.on_tool_error`

```python theme={null}
on_tool_error(
    self,
    error: BaseException,
    *,
    run_id: UUID,
    parent_run_id: UUID | None = None,
    **kwargs: Any,
) -> None
```

End the tool run's span at ERROR.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `error` | `BaseException` | — | — |
| `run_id` | `UUID` | — | — |
| `parent_run_id` | `UUID \| None` | `None` | — |
| `kwargs` | `Any` | `{}` | — |

#### on\_retriever\_start

`tai42_kit.llm.monitoring_callbacks.MonitoringCallbackHandler.on_retriever_start`

```python theme={null}
on_retriever_start(
    self,
    serialized: dict[str, Any] | None,
    query: str,
    *,
    run_id: UUID,
    parent_run_id: UUID | None = None,
    **kwargs: Any,
) -> None
```

Open the retriever run's span (a tool record) with its query.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `serialized` | `dict[str, Any] \| None` | — | — |
| `query` | `str` | — | — |
| `run_id` | `UUID` | — | — |
| `parent_run_id` | `UUID \| None` | `None` | — |
| `kwargs` | `Any` | `{}` | — |

#### on\_retriever\_end

`tai42_kit.llm.monitoring_callbacks.MonitoringCallbackHandler.on_retriever_end`

```python theme={null}
on_retriever_end(
    self,
    documents: Sequence[Any],
    *,
    run_id: UUID,
    parent_run_id: UUID | None = None,
    **kwargs: Any,
) -> None
```

Record the retrieved documents and end the span.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `documents` | `Sequence[Any]` | — | — |
| `run_id` | `UUID` | — | — |
| `parent_run_id` | `UUID \| None` | `None` | — |
| `kwargs` | `Any` | `{}` | — |

#### on\_retriever\_error

`tai42_kit.llm.monitoring_callbacks.MonitoringCallbackHandler.on_retriever_error`

```python theme={null}
on_retriever_error(
    self,
    error: BaseException,
    *,
    run_id: UUID,
    parent_run_id: UUID | None = None,
    **kwargs: Any,
) -> None
```

End the retriever run's span at ERROR.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `error` | `BaseException` | — | — |
| `run_id` | `UUID` | — | — |
| `parent_run_id` | `UUID \| None` | `None` | — |
| `kwargs` | `Any` | `{}` | — |

## RunTrace

`tai42_kit.llm.run_trace.RunTrace`

```python theme={null}
class RunTrace
```

The resolved lineage of one run plus the per-invoke config that records it.

`context` is the trace/span lineage the run's spans join; `config` is the caller's
LangGraph run config (a `RunnableConfig`-shaped mapping) copied by value with the
monitoring callback handler appended after the caller's own callbacks.

**Attributes**

| Attribute | Type |
| - | - |
| `context` | `TraceContext` |
| `config` | `dict[str, Any]` |

## ToolNameTooLongError

`tai42_kit.llm.models.ToolNameTooLongError`

```python theme={null}
class ToolNameTooLongError(ValueError)
```

A tool name is longer than a bound tool name may be.

## bind\_run\_trace

`tai42_kit.llm.run_trace.bind_run_trace`

```python theme={null}
bind_run_trace(
    config: dict[str, Any] | None = None,
    *,
    grouping_nodes: frozenset[str] = frozenset(),
    chain_payloads: ChainPayloads = 'references',
) -> RunTrace
```

Resolve the run's lineage and return the per-invoke config carrying the monitoring callbacks.

Resolves the lineage with `resolve_trace_context` (its `InvalidRunTraceError` propagates) and
returns a `RunTrace` whose `config` is `config` copied by value — a fresh top-level mapping, a fresh
`configurable`, and a fresh `callbacks` list — so one base config can feed many
parallel invocations without colliding. When the active writer records
(`is_recording()`), a `MonitoringCallbackHandler` bound to the lineage is
appended after the caller's callbacks; otherwise nothing is appended.

`grouping_nodes` names the framework nodes that hold steps rather than being one.
`chain_payloads='references'` (default) — each chain run records a manifest that
references the record where each value first appeared, by identity; `'producer'` —
the producer records chain-run inputs/outputs itself. A run declared through
`declared_chain_payload` records the producer's `build` result in either mode. Model
and tool runs are recorded in full either way.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `config` | `dict[str, Any] \| None` | `None` | — |
| `grouping_nodes` | `frozenset[str]` | `frozenset()` | — |
| `chain_payloads` | `ChainPayloads` | `'references'` | — |

## check\_tool\_name

`tai42_kit.llm.models.check_tool_name`

```python theme={null}
check_tool_name(name: str) -> None
```

Refuse a tool name longer than `TOOL_NAME_MAX_LEN`.

The bound is the strictest among the providers a bound tool is sent to; a longer name is
refused, never truncated (a truncated name would name a different tool).

**Parameters**

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

## checkpoint\_registry

`tai42_kit.llm.checkpoint.checkpoint_registry.checkpoint_registry`

```python theme={null}
checkpoint_registry() -> CheckpointRegistry
```

Return the CheckpointRegistry for the running event loop.

One registry per loop; after `close_all()` the next call builds a fresh
registry instead of returning the closed one.

## declared\_chain\_payload

`tai42_kit.llm.monitoring_callbacks.declared_chain_payload`

```python theme={null}
declared_chain_payload(run_id: UUID, build: Callable[[Any], Any]) -> Iterator[None]
```

Record `build(inputs)` / `build(outputs)` as the payloads of LangChain run `run_id` started in the block.

The producer passes `config["run_id"] = run_id` to the run it starts (LangChain names
exactly that one run with it). `build` is called while the run's span is current, so
it may read `writer.current_span_id()`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `run_id` | `UUID` | — | — |
| `build` | `Callable[[Any], Any]` | — | — |

## get\_classifier

`tai42_kit.llm.classifier.get_classifier`

```python theme={null}
get_classifier(provider: str, **kwargs) -> Runnable[ClassifyRequest, ClassifyResponse]
```

Build (or return the cached) classifier runnable for `provider` with the given kwargs.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `provider` | `str` | — | — |
| `kwargs` | — | `{}` | — |

## get\_classifier\_async

`tai42_kit.llm.classifier.get_classifier_async`

```python theme={null}
async get_classifier_async(provider: str, **kwargs) -> Runnable[ClassifyRequest, ClassifyResponse]
```

Build (or return the cached) classifier runnable for `provider`, off the event loop.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `provider` | `str` | — | — |
| `kwargs` | — | `{}` | — |

## get\_embedding

`tai42_kit.llm.embedding.get_embedding`

```python theme={null}
get_embedding(provider: str, **kwargs) -> Embeddings
```

Build (or return the cached) `Embeddings` client for `provider` with the given kwargs.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `provider` | `str` | — | — |
| `kwargs` | — | `{}` | — |

## get\_embedding\_async

`tai42_kit.llm.embedding.get_embedding_async`

```python theme={null}
async get_embedding_async(provider: str, **kwargs) -> Embeddings
```

Build (or return the cached) `Embeddings` client for `provider`, off the event loop.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `provider` | `str` | — | — |
| `kwargs` | — | `{}` | — |

## get\_llm

`tai42_kit.llm.models.get_llm`

```python theme={null}
get_llm(provider: str, **kwargs) -> BaseChatModel
```

Build (or return the cached) chat model for `provider` with the given kwargs.

A set `reasoning_effort` is validated against the built model's declared
capability after construction: the generic effort lever reaches the provider
constructor as a kwarg, and a level the model does not declare is refused loudly
here (see `_validate_reasoning_effort`) rather than failing opaquely on the
wire.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `provider` | `str` | — | — |
| `kwargs` | — | `{}` | — |

## get\_llm\_async

`tai42_kit.llm.models.get_llm_async`

```python theme={null}
async get_llm_async(provider: str, **kwargs) -> BaseChatModel
```

Build the chat model for `provider` in a worker thread, off the event loop.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `provider` | `str` | — | — |
| `kwargs` | — | `{}` | — |

## release\_loop\_bound\_resources

`tai42_kit.llm._resource_registry.release_loop_bound_resources`

```python theme={null}
async release_loop_bound_resources(*, all_epochs: bool = False) -> None
```

Close every loop-bound kit registry's resources on the running loop.

Closes the current epoch's registry of every map (with `all_epochs`, every retired
epoch's registry held for this loop too). Every registry is tried even after a failure;
the failures are raised together as one `ExceptionGroup`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `all_epochs` | `bool` | `False` | — |

## resolve\_trace\_context

`tai42_kit.llm.run_trace.resolve_trace_context`

```python theme={null}
resolve_trace_context(config: dict[str, Any] | None = None) -> TraceContext
```

Resolve the one trace lineage for a run from `config` and the ambient deposit.

Precedence: an explicit `configurable[MONITORING_TRACE_ID_KEY]` (with its optional
`MONITORING_PARENT_SPAN_ID_KEY` anchor) wins; else the ambient
`get_ambient_trace_context` deposit; else a fresh
32-hex root trace with no parent. Pure — reads only, mints no side effect.

An explicit trace id that is not 32 lower-hex (not all zeros), or a caller's parent anchor that is not 16
lower-hex (not all zeros), is refused with `InvalidRunTraceError`: a run never proceeds under a lineage
no writer can record. An empty explicit trace id reads as absent.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `config` | `dict[str, Any] \| None` | `None` | — |

## store\_registry

`tai42_kit.llm.store.store_registry.store_registry`

```python theme={null}
store_registry() -> StoreRegistry
```

Return the StoreRegistry for the running event loop.

One registry per loop; after `close_all()` the next call builds a fresh
registry instead of returning the closed one.

## system\_prompt\_cache\_mark

`tai42_kit.llm.models.system_prompt_cache_mark`

```python theme={null}
system_prompt_cache_mark(provider: str) -> dict[str, Any] | None
```

The content-block kwargs that mark `provider`'s system prompt for caching, or `None`.

A provider that takes an explicit system-prompt cache breakpoint returns the
`system_content_kwargs` that carry it (the block `build_system_message` merges onto
the system message); a provider that caches its prefixes with no mark, or does not cache,
returns `None`. The `match` mirrors `_build_llm`'s so a provider name never leaves
this module and an unknown provider is refused loudly rather than silently un-marked.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `provider` | `str` | — | — |

Classifier model factory and its provider-agnostic contract.

A classifier judges JSON-compatible state against typed questions and returns
typed answers — JSON in, JSON out. Three question kinds cover the common
judgments: a binary `noul` (the probability that the answer is yes), a
categorical `choice` (one label from a fixed set, with a probability for every
label), and an ordinal `score` (an expected value over an ordered rubric). A
request pairs the state with a named mapping of questions; the response carries
one answer per question, token usage, and the provider's request id.

These pydantic models ARE the platform's classifier contract.
`get_classifier` and `get_classifier_async` build a cached,
provider-keyed runnable that accepts a `ClassifyRequest` and returns a
`ClassifyResponse`; each provider adapts this contract to its own wire
shape behind the factory. The models take no vendor import, so the contract can
be read and constructed without any provider package installed.

Every set a request declares is enforced by the factory's runnable on every
call, whatever the provider: one answer per question name, of the question's
kind; a `choice` label from the keys of its `criteria`; a `score` over
its levels. A response outside any of them raises `ClassifierAnswerError`,
so a caller never receives an answer it did not declare.

## QuestionContent

`tai42_kit.llm.classifier.QuestionContent`

```python theme={null}
QuestionContent = str | dict[str, JsonValue] | list[JsonValue]
```

Instruction text or structured content the classifier judges against: free text, a JSON object, or a JSON array.

## NoulCriteria

`tai42_kit.llm.classifier.NoulCriteria`

```python theme={null}
class NoulCriteria(BaseModel)
```

Optional descriptions of what the yes and no outcomes of a noul question mean.

**Attributes**

| Attribute | Type |
| - | - |
| `true` | `JsonValue` |
| `false` | `JsonValue` |

## NoulQuestion

`tai42_kit.llm.classifier.NoulQuestion`

```python theme={null}
class NoulQuestion(BaseModel)
```

Binary question: judge the state and return the probability that the answer is yes.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['noul']` |
| `instructions` | `QuestionContent` |
| `criteria` | `NoulCriteria \| None` |

## ChoiceQuestion

`tai42_kit.llm.classifier.ChoiceQuestion`

```python theme={null}
class ChoiceQuestion(BaseModel)
```

Categorical question: pick one label from `criteria`, keyed by label to its description.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['choice']` |
| `instructions` | `QuestionContent` |
| `criteria` | `dict[str, JsonValue]` |

## ScoreQuestion

`tai42_kit.llm.classifier.ScoreQuestion`

```python theme={null}
class ScoreQuestion(BaseModel)
```

Ordinal question: rate the state against `criteria`, an ordered rubric of two or more levels.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['score']` |
| `instructions` | `QuestionContent` |
| `criteria` | `list[JsonValue]` |

## ClassifyQuestion

`tai42_kit.llm.classifier.ClassifyQuestion`

```python theme={null}
ClassifyQuestion = Annotated[NoulQuestion | ChoiceQuestion | ScoreQuestion, Field(discriminator='type')]
```

A question of one of the three kinds, discriminated on `type`.

## ClassifyRequest

`tai42_kit.llm.classifier.ClassifyRequest`

```python theme={null}
class ClassifyRequest(BaseModel)
```

The state to judge together with the named questions to answer about it.

**Attributes**

| Attribute | Type |
| - | - |
| `state` | `JsonValue` |
| `questions` | `dict[str, ClassifyQuestion]` |

## NoulAnswer

`tai42_kit.llm.classifier.NoulAnswer`

```python theme={null}
class NoulAnswer(BaseModel)
```

The probability, from 0 to 1, that a noul question's answer is yes.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['noul']` |
| `noul` | `float` |

## ChoiceAnswer

`tai42_kit.llm.classifier.ChoiceAnswer`

```python theme={null}
class ChoiceAnswer(BaseModel)
```

The selected label of a choice question, its per-label probabilities, and a confidence.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['choice']` |
| `choice` | `str` |
| `probabilities` | `dict[str, float]` |
| `confidence` | `float` |

## ScoreAnswer

`tai42_kit.llm.classifier.ScoreAnswer`

```python theme={null}
class ScoreAnswer(BaseModel)
```

The expected value of a score question, the level legend and distribution, and a confidence.

**Attributes**

| Attribute | Type |
| - | - |
| `type` | `Literal['score']` |
| `score` | `float` |
| `legend` | `dict[int, JsonValue]` |
| `probabilities` | `dict[int, float]` |
| `confidence` | `float` |

## ClassifyAnswer

`tai42_kit.llm.classifier.ClassifyAnswer`

```python theme={null}
ClassifyAnswer = Annotated[NoulAnswer | ChoiceAnswer | ScoreAnswer, Field(discriminator='type')]
```

An answer of one of the three kinds, discriminated on `type`.

## ClassifierAnswerError

`tai42_kit.llm.classifier.ClassifierAnswerError`

```python theme={null}
class ClassifierAnswerError(Exception)
```

The provider's response falls outside a set its request declares.

A request declares its question names and each question's kind; a `choice` question
declares its labels (the keys of its `criteria`) and a `score` question its levels
(`0` to `len(criteria) - 1`). A response that answers other questions, answers one
with another kind, picks a label outside the labels, scores outside the levels, or keys
its probabilities or legend by anything but exactly those labels or levels breaks the
classifier contract. The request was valid, so the failure is the provider's, and the
message names the question, what the provider gave, and what was declared.

## ClassifyUsage

`tai42_kit.llm.classifier.ClassifyUsage`

```python theme={null}
class ClassifyUsage(BaseModel)
```

Token usage reported for a classification request; either count may be unreported.

**Attributes**

| Attribute | Type |
| - | - |
| `input_tokens` | `int \| None` |
| `output_tokens` | `int \| None` |

## ClassifyResponse

`tai42_kit.llm.classifier.ClassifyResponse`

```python theme={null}
class ClassifyResponse(BaseModel)
```

One answer per requested question, plus the model, token usage, and provider request id.

**Attributes**

| Attribute | Type |
| - | - |
| `model` | `str` |
| `answers` | `dict[str, ClassifyAnswer]` |
| `usage` | `ClassifyUsage` |
| `request_id` | `str \| None` |


# Logging (tai42_kit.logging)
Source: https://docs.tai42.ai/reference/python-sdk/kit-logging

Structured logging settings and setup.

Logging settings, setup and the process log-redaction registries.

Side-effect-free on import: the consumer calls `setup_logging(...)` and
`install_record_redaction(...)` explicitly (e.g. at app startup), and a feature
registers its own redaction patterns — importing this package configures nothing.

## REDACTOR\_FAILED

`tai42_kit.logging.redaction.REDACTOR_FAILED`

```python theme={null}
REDACTOR_FAILED: Final = '[log redactor error: record suppressed]'
```

## TRANSPORT\_LOGGERS

`tai42_kit.logging.redaction.TRANSPORT_LOGGERS`

```python theme={null}
TRANSPORT_LOGGERS: Final = ('httpx', 'httpcore')
```

## URL\_REDACTION

`tai42_kit.logging.redaction.URL_REDACTION`

```python theme={null}
URL_REDACTION: Final = '***'
```

## AccessLogQueryMaskingFilter

`tai42_kit.logging.logger.AccessLogQueryMaskingFilter`

```python theme={null}
class AccessLogQueryMaskingFilter(logging.Filter)
```

Mask every query-string value in the `uvicorn.access` request line.

The access formatter REBUILDS the line from `record.args` — a 5-tuple whose third
element is the request path + query — and ignores a rewritten `record.msg`, so the
mask is applied by replacing that args element; masking the message alone silently
no-ops. Non-matching records pass through untouched. Always returns `True` — this
filter redacts, it never drops.

### Members

#### filter

`tai42_kit.logging.logger.AccessLogQueryMaskingFilter.filter`

```python theme={null}
filter(self, record: logging.LogRecord) -> bool
```

Mask the request path in a matching access record and always keep the record.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `record` | `logging.LogRecord` | — | — |

## LoggingSettings

`tai42_kit.logging.settings.LoggingSettings`

```python theme={null}
class LoggingSettings(TaiBaseSettings)
```

Process logging configuration sourced from `TAI_`-prefixed environment variables.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `log_level` | `str` |

### Members

#### validate\_log\_level

`tai42_kit.logging.settings.LoggingSettings.validate_log_level`

```python theme={null}
validate_log_level(cls, v: str) -> str
```

Normalise `log_level` to upper case, raising when it is not a known level name.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `v` | `str` | — | — |

#### is\_enabled\_for

`tai42_kit.logging.settings.LoggingSettings.is_enabled_for`

```python theme={null}
is_enabled_for(self, level_name: str) -> bool
```

Whether the configured level would emit a record logged at `level_name`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `level_name` | `str` | — | — |

## RecordScope

`tai42_kit.logging.redaction.RecordScope`

```python theme={null}
RecordScope = Literal['tai', 'process']
```

## install\_record\_redaction

`tai42_kit.logging.redaction.install_record_redaction`

```python theme={null}
install_record_redaction(scope: RecordScope = 'tai') -> None
```

Chain one redacting wrapper over `logging.getLogRecordFactory()`.

`"tai"` scrubs the tai logger family (`tai`, `mcp`, `fastmcp` and names
starting `tai42_`, `tai42.`, `tai.`, `mcp.`, `fastmcp.`), so an embedding
host's own records pass untouched; `"process"` scrubs every record. The scope
only widens: a later `"tai"` install never narrows `"process"`. Idempotent:
the wrapper is tagged and a repeat install chains nothing.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `scope` | `RecordScope` | `'tai'` | — |

## logging\_settings

`tai42_kit.logging.settings.logging_settings`

```python theme={null}
logging_settings() -> LoggingSettings
```

Return the cached `LoggingSettings` instance.

## redact\_url\_userinfo

`tai42_kit.logging.redaction.redact_url_userinfo`

```python theme={null}
redact_url_userinfo(url: str) -> str
```

`scheme://user:pass@host/…` -> `scheme://***@host/…`.

The authority ends at the first `/`, `?` or `#`; the userinfo runs to its
last `@`, so an `@` inside a password cannot leak. A string with no `://`
or no `@` in its authority is returned unchanged.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `url` | `str` | — | — |

## redact\_urls\_in\_text

`tai42_kit.logging.redaction.redact_urls_in_text`

```python theme={null}
redact_urls_in_text(text: str) -> str
```

Mask every URL in free text: its userinfo and every query-string value become `***`.

Non-URL text is left untouched.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `text` | `str` | — | — |

## register\_record\_redactor

`tai42_kit.logging.redaction.register_record_redactor`

```python theme={null}
register_record_redactor(name: str, *, markers: tuple[str, ...], redact: Callable[[str], str]) -> None
```

Register (or replace, by `name`) a redactor the record factory applies to in-scope records.

Registration alone installs nothing; `install_record_redaction` chains the
factory. Raises `ValueError` when `markers` is empty or holds anything but a
non-empty string.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `markers` | `tuple[str, ...]` | — | — |
| `redact` | `Callable[[str], str]` | — | — |

## register\_transport\_redaction

`tai42_kit.logging.redaction.register_transport_redaction`

```python theme={null}
register_transport_redaction(name: str, *, markers: tuple[str, ...], redact: Callable[[str], str]) -> None
```

Register (or replace, by `name`) a redactor for the `TRANSPORT_LOGGERS` records.

Installs, once, one filter on each transport logger that applies every
registered transport redactor. Raises `ValueError` when `markers` is empty or
holds anything but a non-empty string.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `markers` | `tuple[str, ...]` | — | — |
| `redact` | `Callable[[str], str]` | — | — |

## setup\_logging

`tai42_kit.logging.logger.setup_logging`

```python theme={null}
setup_logging(settings: LoggingSettings) -> None
```

Configure the ROOT logger for an application.

Call this from application startup only — never on library import, since it
reconfigures the process-global root logger. `force=True` replaces the
existing root handlers, so a repeat call (e.g. after a settings reload)
applies the new level instead of being silently ignored.

The `uvicorn.access` logger's request line carries the full request URL — including
query-string capability codes and opaque params — so it is fitted with a masking filter
that redacts every query VALUE before the line is formatted. The `httpx` logger's own
request-line log carries the full outbound URL, credentials included, so it is fitted
with a filter that strips the path and query, leaving only the origin. Both attaches are
idempotent: a repeat call never stacks a second filter.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `settings` | `LoggingSettings` | — | — |


# Network guard (tai42_kit.net)
Source: https://docs.tai42.ai/reference/python-sdk/kit-net

The URL guard and safe fetch helpers.

SSRF-guarded server-side URL fetching.

The SSRF guard (`tai42_kit.net.url_guard`) resolves and validates each target
host, and `fetch_url` is the httpx download built on it: while the guard is
enabled (the default) that download is DNS-rebinding-safe, redirect-safe, and
size-capped. `guarded_request` is the single guarded GET/POST/DELETE beside it
(no redirects followed, a size cap, one total deadline). The guard is reusable on its
own by any caller that fetches a caller-supplied URL server-side over its own HTTP client.

`fetch_url`, `fetch_media` and `guarded_request` are re-exported LAZILY (PEP 562): they pull in
`httpx`/`httpcore`, and a consumer of a lighter `net` utility (e.g.
`tai42_kit.net.request_body`) must not drag that backend into its import graph merely
by importing a sibling module. This is the same reason `tai42_kit.net.jwt` (which
needs `joserfc`) stays out of this re-export.

## GuardedRequestError

`tai42_kit.net.guarded_request.GuardedRequestError`

```python theme={null}
class GuardedRequestError(Exception)
```

A guarded request that reached no usable answer: a transport failure or a body over the cap.

## GuardedRequestTimeoutError

`tai42_kit.net.guarded_request.GuardedRequestTimeoutError`

```python theme={null}
class GuardedRequestTimeoutError(GuardedRequestError)
```

A guarded request that did not complete within its total deadline.

## GuardedResponse

`tai42_kit.net.guarded_request.GuardedResponse`

```python theme={null}
class GuardedResponse
```

The complete answer to a guarded request: status, headers and the whole (capped) body.

**Attributes**

| Attribute | Type |
| - | - |
| `status` | `int` |
| `headers` | `httpx.Headers` |
| `body` | `bytes` |

## MediaFetchError

`tai42_kit.net.fetch_media.MediaFetchError`

```python theme={null}
class MediaFetchError(Exception)
```

A vendor media fetch failed at the HTTP or transport layer.

The message carries the vendor HOST plus the HTTP status code or the
transport-exception class ONLY — never the request URL — so a credential riding
the URL path or query never reaches an error string. `status_code` is the HTTP
status when the fault was an error response (or an unfollowed redirect), else
`None` (a transport fault — timeout, connection error, a torn read — or a
malformed response header). `transient` tells the caller whether a redelivery
could plausibly succeed; it is derived from the status — a 5xx, a 408 (Request
Timeout) or a 429 (Too Many Requests, a vendor throttle) is transient, and so is a
transport fault (status `None`); every other 4xx/3xx is permanent — unless an
explicit value is given for a fault the status cannot classify (a malformed response
header is permanent).

**Attributes**

| Attribute | Type |
| - | - |
| `host` | — |
| `status_code` | — |
| `cause_class` | — |
| `transient` | — |

## MediaStream

`tai42_kit.net.fetch_media.MediaStream`

```python theme={null}
class MediaStream
```

A vendor media response opened for streaming — the final hop's metadata plus its body.

`content_type` is the final response's `Content-Type` media type with parameters
stripped and lower-cased (`None` when the header is absent or empty).
`content_length` is the parsed `Content-Length` (`None` when absent). `host` is
the final response's host, for error/log text only — never the URL. `chunks` yields
the body as it arrives; a fault while iterating raises `MediaFetchError`
(`transient=True`, URL-free).

**Attributes**

| Attribute | Type |
| - | - |
| `content_type` | `str \| None` |
| `content_length` | `int \| None` |
| `host` | `str` |
| `chunks` | `AsyncIterator[bytes]` |

## UrlGuardError

`tai42_kit.net.url_guard.UrlGuardError`

```python theme={null}
class UrlGuardError(Exception)
```

Raised when a target host is unresolvable, non-public, over the size cap, or over-redirected.

Covers a host that cannot be resolved or is rejected as non-public, a response that
exceeds the guard's size cap, and a redirect chain that exceeds `max_redirects`.

## UrlGuardSettings

`tai42_kit.net.url_guard.UrlGuardSettings`

```python theme={null}
class UrlGuardSettings(TaiBaseSettings)
```

Policy for the SSRF guard on server-side URL fetches.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `enabled` | `bool` |
| `allow_cidrs` | `list[str]` |
| `max_response_bytes` | `int` |
| `max_redirects` | `int` |

## enforce\_size

`tai42_kit.net.url_guard.enforce_size`

```python theme={null}
enforce_size(nbytes: int) -> None
```

Raise `UrlGuardError` when `nbytes` exceeds the configured cap.

A no-op when the guard is disabled. Never truncates — an over-cap response is
refused loudly.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `nbytes` | `int` | — | — |

## fetch\_media

`tai42_kit.net.fetch_media.fetch_media`

```python theme={null}
async fetch_media(
    url: str,
    *,
    headers: dict[str, str] | None = None,
    auth: httpx.Auth | tuple[str, str] | None = None,
    follow_redirects: bool = False,
    max_bytes: int,
) -> tuple[bytes, str | None]
```

Fetch a vendor media object bounded by `max_bytes`, SSRF-pinned while the guard is enabled.

Shares the streaming primitive `_stream_media` with `open_media_stream` and collects
its body, raising `RequestBodyTooLargeError` (never
truncating) the instant the running total crosses `max_bytes`. Redirect handling, the
cross-origin credential drop, and the URL-free faults are exactly those of
`open_media_stream`. Returns `(bytes, media type)` where the media type is the response
`Content-Type` with parameters stripped and lower-cased (`None` when absent).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `url` | `str` | — | — |
| `headers` | `dict[str, str] \| None` | `None` | — |
| `auth` | `httpx.Auth \| tuple[str, str] \| None` | `None` | — |
| `follow_redirects` | `bool` | `False` | — |
| `max_bytes` | `int` | — | — |

## fetch\_url

`tai42_kit.net.fetch_url.fetch_url`

```python theme={null}
async fetch_url(url: str) -> tuple[bytes, str | None]
```

Fetch the URL's body and return `(bytes, mime)`.

`mime` is the response `Content-Type` header (`None` when absent). When
the guard is enabled the request runs over `PinningTransport`, which
validates and pins every connection (initial request and each redirect hop
that opens a new connection), and the body is size-capped while streaming.
Raises rather than truncating an over-cap body or reaching a non-public host.
When the guard is disabled a plain client is used, which caps nothing, pins
nothing, and lets httpx follow redirects.

Under the guard, redirects are followed one hop at a time rather than by
httpx, which reads each intermediate body into memory in full before chasing
`Location`. A hop carrying a body large enough to exhaust memory would slip
past the cap that way, so each redirect response is closed unread — forgoing
connection reuse for that hop — and only the terminal body is streamed and
counted.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `url` | `str` | — | — |

## guard\_enabled

`tai42_kit.net.url_guard.guard_enabled`

```python theme={null}
guard_enabled() -> bool
```

Return whether the SSRF guard is enabled (`TAI_URL_GUARD_ENABLED`).

## guarded\_request

`tai42_kit.net.guarded_request.guarded_request`

```python theme={null}
async guarded_request(
    method: str,
    url: str,
    *,
    headers: Mapping[str, str] | None = None,
    form: Mapping[str, str] | None = None,
    json_body: Any = None,
    timeout: float,
    max_bytes: int,
) -> GuardedResponse
```

Send one guarded request and return its complete answer, whatever its status.

Raises `UrlGuardError` when the URL is refused (not `https` on
a non-loopback host, or a host the guard blocks), `GuardedRequestTimeoutError` when the
whole call outlasts `timeout` seconds, and `GuardedRequestError` on a transport failure
or a body over `max_bytes`. `form` is sent form-encoded, `json_body` as JSON; at most one.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `method` | `str` | — | — |
| `url` | `str` | — | — |
| `headers` | `Mapping[str, str] \| None` | `None` | — |
| `form` | `Mapping[str, str] \| None` | `None` | — |
| `json_body` | `Any` | `None` | — |
| `timeout` | `float` | — | — |
| `max_bytes` | `int` | — | — |

## is\_loopback\_host

`tai42_kit.net.url_guard.is_loopback_host`

```python theme={null}
is_loopback_host(host: str) -> bool
```

Whether `host` names this machine: `localhost` or a loopback IP literal (`127.0.0.0/8`, `::1`).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `host` | `str` | — | — |

## open\_media\_stream

`tai42_kit.net.fetch_media.open_media_stream`

```python theme={null}
async open_media_stream(
    url: str,
    *,
    headers: Mapping[str, str] | None = None,
    auth: tuple[str, str] | None = None,
    follow_redirects: bool = False,
) -> AsyncIterator[MediaStream]
```

Open a vendor media object for streaming, SSRF-pinned while the guard is enabled.

While `guard_enabled` is set the request runs over the
`PinningTransport`; when it is unset a plain transport
that pins nothing is used instead — the same one operator switch `fetch_url` honours.
When `follow_redirects` is set, redirects are followed hop-by-hop up to the guard's
`max_redirects` (`follow_redirects` is never handed to httpx, so the pin re-runs per
hop while enabled); when it is not, an unfollowed redirect is a fault. `headers`/`auth`
carry the vendor credential on the call only — never returned, never logged; `auth` is a
Basic-auth `(username, password)` pair only. On a cross-origin hop, and every hop after
it, the request carries no caller-supplied header and no `auth` (only httpx's defaults); a
same-origin hop keeps them.

Yields a `MediaStream` for the final response; the response is closed when the
context exits, including on an exception raised while iterating `chunks`. Faults never
carry the request URL: an SSRF rejection surfaces as
`UrlGuardError` (host only); an HTTP-status, transport,
or malformed-header fault as `MediaFetchError` (vendor host + status/class only) —
at open, or from the `chunks` iterator on a mid-body fault.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `url` | `str` | — | — |
| `headers` | `Mapping[str, str] \| None` | `None` | — |
| `auth` | `tuple[str, str] \| None` | `None` | — |
| `follow_redirects` | `bool` | `False` | — |

## resolve\_and\_validate

`tai42_kit.net.url_guard.resolve_and_validate`

```python theme={null}
async resolve_and_validate(host: str) -> str
```

Resolve `host`, reject non-public addresses, and return the first validated address.

The returned address is the one to connect to (the "pin").

Resolving once and connecting to the returned address closes DNS-rebinding:
the same lookup that is validated is the one the connection uses, so an
attacker cannot answer public during the check and internal at connect time.
Raises `UrlGuardError` if resolution fails or any address is blocked.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `host` | `str` | — | — |

## url\_guard\_settings

`tai42_kit.net.url_guard.url_guard_settings`

```python theme={null}
url_guard_settings() -> UrlGuardSettings
```

Return the process-wide `UrlGuardSettings`, cached after first load.


# Plugin I/O and env (tai42_kit.plugins)
Source: https://docs.tai42.ai/reference/python-sdk/kit-plugins

Loading a tai-plugin.yml, reading its docs, and deriving the env a spec requires.

Plugin-spec loading: the YAML I/O for `tai-plugin.yml`.

Every installable TAI plugin ships a `tai-plugin.yml` — at its repo root and
as package-data inside the built wheel. The schema is
`tai42_contract.plugins.PluginSpec`; these helpers do the YAML reading the
pure contract cannot (the contract has no YAML dependency) and validate loudly.
`parse_plugin_spec` is the shared low-level entry point — it validates
spec content already in memory (`bytes` or `str`), and both loaders route
through it.

Because a spec may arrive as untrusted network input (an artifact fetched from
a registry, a wheel of unknown provenance), parsing is hardened against
resource-exhaustion and ambiguity attacks: content larger than
`MAX_PLUGIN_SPEC_BYTES` is rejected before parsing; YAML anchors/aliases
(the billion-laughs expansion vector) and duplicate mapping keys (silent
last-value-wins) are rejected outright; deeply nested documents that exhaust the
interpreter stack are caught. A flat `tai-plugin.yml` needs none of those
constructs, so rejecting them costs nothing.

Failure surface: content- and file-level problems (over-size input, missing
file, non-UTF-8 bytes, unparseable YAML, anchors/aliases, duplicate keys,
excessive nesting, a non-mapping document, a wheel with zero or several spec
files, an unreadable archive) raise `PluginSpecLoadError`; schema
violations inside a well-formed document propagate pydantic's
`ValidationError`, which already names every offending field. Nothing
degrades silently.

## MAX\_DOCS\_FILE\_BYTES

`tai42_kit.plugins.MAX_DOCS_FILE_BYTES`

```python theme={null}
MAX_DOCS_FILE_BYTES = 2 * 1024 * 1024
```

## MAX\_DOCS\_TOTAL\_BYTES

`tai42_kit.plugins.MAX_DOCS_TOTAL_BYTES`

```python theme={null}
MAX_DOCS_TOTAL_BYTES = 16 * 1024 * 1024
```

## MAX\_PLUGIN\_SPEC\_BYTES

`tai42_kit.plugins.MAX_PLUGIN_SPEC_BYTES`

```python theme={null}
MAX_PLUGIN_SPEC_BYTES = 256 * 1024
```

## MDX\_SAFE\_COMPONENTS

`tai42_kit.plugins.MDX_SAFE_COMPONENTS`

```python theme={null}
MDX_SAFE_COMPONENTS: frozenset[str] = frozenset()
```

## PLUGIN\_DOCS\_DIRNAME

`tai42_kit.plugins.PLUGIN_DOCS_DIRNAME`

```python theme={null}
PLUGIN_DOCS_DIRNAME = 'docs'
```

## PLUGIN\_DOCS\_INDEX

`tai42_kit.plugins.PLUGIN_DOCS_INDEX`

```python theme={null}
PLUGIN_DOCS_INDEX = 'docs/index.mdx'
```

## PLUGIN\_SPEC\_FILENAME

`tai42_kit.plugins.PLUGIN_SPEC_FILENAME`

```python theme={null}
PLUGIN_SPEC_FILENAME = 'tai-plugin.yml'
```

## EnvRequirement

`tai42_kit.plugins.EnvRequirement`

```python theme={null}
class EnvRequirement
```

One environment variable an installed plugin item requires.

`name` is the variable name; `secret` marks a value the platform masks
in views and profile snapshots. Secret-ness is a property of the requirement
the spec DECLARES (an OAuth client secret), not of the marker grammar — a
`!ENV` marker cannot know whether its value is sensitive, so marker-derived
requirements are never secret here.

**Attributes**

| Attribute | Type |
| - | - |
| `name` | `str` |
| `secret` | `bool` |

## PluginDocsError

`tai42_kit.plugins.PluginDocsError`

```python theme={null}
class PluginDocsError(Exception)
```

Raised when a plugin's in-wheel `docs/` tree cannot be read or fails the canonical validation contract.

Covers both the extraction family (missing tree, a traversing/absolute
member, an over-ceiling or bomb member, an unreadable archive) and every
`validate_docs` violation (set-shape, front matter, unresolvable
reference, forbidden scheme, un-whitelisted mdx). Nothing degrades silently.

## PluginSpecLoadError

`tai42_kit.plugins.PluginSpecLoadError`

```python theme={null}
class PluginSpecLoadError(Exception)
```

Raised when a `tai-plugin.yml` cannot be located, read, or parsed.

Covers the I/O and structural-safety failure family only; a well-formed
YAML mapping that violates the schema raises pydantic's `ValidationError`
instead.

## accepts\_env

`tai42_kit.plugins.accepts_env`

```python theme={null}
accepts_env(spec: PluginSpec) -> bool
```

Whether the installer offers an env-supply step for this spec.

True iff any item carries at least one `!ENV` marker (required OR defaulted
— an operator may override even a defaulted marker) or the spec has a
non-empty `required_env_for_spec`. This is the installer's
env-acceptance and routing key.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `spec` | `PluginSpec` | — | — |

## load\_plugin\_spec

`tai42_kit.plugins.load_plugin_spec`

```python theme={null}
load_plugin_spec(path: Path) -> PluginSpec
```

Load and validate the `tai-plugin.yml` at `path`.

Raises `PluginSpecLoadError` for an unreadable or over-size file,
non-UTF-8 bytes, invalid YAML, or a non-mapping document; pydantic
`ValidationError` for schema violations. Never returns a partial or
defaulted spec.

The on-disk size is checked against `MAX_PLUGIN_SPEC_BYTES` via
`stat` *before* any bytes are read, so a multi-gigabyte file is refused
without being slurped into memory. The bytes are then handed to
`parse_plugin_spec`, which enforces the byte cap and UTF-8 decode
uniformly with the wheel and in-memory paths — so a non-UTF-8 file raises
`PluginSpecLoadError` rather than escaping as `UnicodeDecodeError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `Path` | — | — |

## parse\_plugin\_spec

`tai42_kit.plugins.parse_plugin_spec`

```python theme={null}
parse_plugin_spec(data: bytes | str, *, source: str = PLUGIN_SPEC_FILENAME) -> PluginSpec
```

Parse and validate `tai-plugin.yml` content already in memory.

The shared low-level entry point: `load_plugin_spec` and
`read_wheel_plugin_spec` both route through it, and callers holding
raw bytes (e.g. an artifact fetched over the network) validate through it
directly. `source` names the content's origin in error messages. Raises
`PluginSpecLoadError` for over-size input, non-UTF-8 bytes, invalid
YAML, anchors/aliases, duplicate keys, excessive nesting, or a non-mapping
document; pydantic `ValidationError` for schema violations.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `data` | `bytes \| str` | — | — |
| `source` | `str` | `PLUGIN_SPEC_FILENAME` | — |

## read\_dir\_docs

`tai42_kit.plugins.read_dir_docs`

```python theme={null}
read_dir_docs(plugin_dir: Path) -> dict[str, bytes]
```

Read the `docs/` tree sitting beside `tai-plugin.yml` in a plugin dir.

The on-disk counterpart of `read_wheel_docs` for a descriptor-only
plugin (no wheel): returns `{relative_path: bytes}` for every file under
`<plugin_dir>/docs/`, keyed from `plugin_dir` so keys begin `docs/`
(e.g. `docs/index.mdx`) exactly as the wheel reader keys them. The same
ceilings apply: a member past `MAX_DOCS_FILE_BYTES` or a cumulative
payload past `MAX_DOCS_TOTAL_BYTES` raises `PluginDocsError`. A
missing `docs/` directory, an empty one, or an unreadable file also raises
`PluginDocsError`. Never returns a partial tree.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `plugin_dir` | `Path` | — | — |

## read\_wheel\_docs

`tai42_kit.plugins.read_wheel_docs`

```python theme={null}
read_wheel_docs(wheel_path: Path) -> dict[str, bytes]
```

Read the `docs/` tree packaged beside `tai-plugin.yml` in the wheel.

Returns `{relative_path: bytes}` for every file under the packaged
`docs/` directory, keyed from the spec's package root so keys begin
`docs/` (e.g. `docs/index.mdx`). The wheel must contain exactly one
`tai-plugin.yml` (as `read_wheel_plugin_spec` requires) with a
`docs/` directory beside it. Zero or several specs, a missing `docs/`
tree, a member escaping via `..` or an absolute path, a member using a
compression method other than stored/deflate, a member inflating past
`MAX_DOCS_FILE_BYTES`, a cumulative payload past
`MAX_DOCS_TOTAL_BYTES`, or an unreadable archive raise
`PluginDocsError`. Never returns a partial tree.

Decompression-bomb discipline mirrors `read_wheel_plugin_spec`: only
`ZIP_STORED`/`ZIP_DEFLATED` members are read (CPython threads the length
cap into the decompressor solely on the deflate path), the caps are enforced
by BOUNDED streamed reads, and `ZipInfo.file_size` — attacker-controlled
central-directory metadata — is never trusted.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `wheel_path` | `Path` | — | — |

## read\_wheel\_plugin\_spec

`tai42_kit.plugins.read_wheel_plugin_spec`

```python theme={null}
read_wheel_plugin_spec(wheel_path: Path) -> PluginSpec
```

Read and validate the spec packaged inside the wheel at `wheel_path`.

The wheel must contain exactly one `tai-plugin.yml` entry (shipped as
package-data in the plugin's import package); zero or several entries, an
unreadable archive, a member using a compression method other than
stored/deflate, an over-size or decompression-bomb member, invalid YAML, or
a non-mapping document raise `PluginSpecLoadError`, and schema
violations raise pydantic's `ValidationError`.

Only `ZIP_STORED` and `ZIP_DEFLATED` members are read: the bounded read
that caps a decompression bomb relies on `ZipExtFile` threading the length
cap into the decompressor, which CPython does only on the deflate path, so a
`ZIP_BZIP2`/`ZIP_LZMA` member would inflate its whole block unbounded.
The compression method is checked before any byte is read.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `wheel_path` | `Path` | — | — |

## required\_env

`tai42_kit.plugins.required_env`

```python theme={null}
required_env(item: PluginItem) -> tuple[EnvRequirement, ...]
```

The environment variables one item requires to install, in first-seen order.

An `mcp-server` item requires each REQUIRED (no-default) `!ENV` marker
var in its `mcp` block — deduped, `secret=False` (the marker cannot know).
An `oauth` connector that names an env client requires its client-credential
pair (`client_id_env` non-secret, `client_secret_env` secret); a discovered one
with a stored client requires nothing. A `none`
connector requires nothing at install (its `config_fields` are supplied by
the end user at connect time), and every other kind requires nothing.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `item` | `PluginItem` | — | — |

## required\_env\_for\_spec

`tai42_kit.plugins.required_env_for_spec`

```python theme={null}
required_env_for_spec(spec: PluginSpec) -> tuple[EnvRequirement, ...]
```

The ordered union of every item's `required_env`, keyed by name.

First-seen order across `spec.provides` is preserved; when the same var is
required by two items with different secret-ness, `secret=True` wins (a
value masked by any requirement stays masked).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `spec` | `PluginSpec` | — | — |

## validate\_docs

`tai42_kit.plugins.validate_docs`

```python theme={null}
validate_docs(files: dict[str, bytes], *, first_party: bool) -> None
```

Validate a docs tree (`{docs-relative-path: bytes}`) against the canonical contract.

Raise `PluginDocsError` on the first violation.
The one implementation every enforcement point shares (marketplace ingest,
the monorepo CI gate, the docs-site generator); each caller owns the
`first_party` policy. Enforced for EVERY namespace: the set shape (only
`.mdx` pages under `docs/` and raster images under `docs/images/` — SVG
and every other type refused, SVG being an XSS surface); a present
`docs/index.mdx`; per-page front matter of exactly `title` +
`description`, each a single-line plain string with no control characters
or fence-breaking metacharacters; and relative link/image references that
resolve within the set. When `first_party` is False, additionally: the mdx
safe-whitelist (`MDX_SAFE_COMPONENTS`) and a link/image scheme of only
http(s) or an in-set relative path — `javascript:`/`data:` refused.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `files` | `dict[str, bytes]` | — | — |
| `first_party` | `bool` | — | — |


# Postgres client (tai42_kit.clients.impl.postgres)
Source: https://docs.tai42.ai/reference/python-sdk/kit-postgres

The pooled Postgres client, autocommit reads, pinned and dedicated connections.

Pooled Postgres client built on `psycopg_pool.AsyncConnectionPool`.

Every pool the kit builds proves its first connection before it is handed out, and that
proof is the one place a connection's establishment is retried (`retry_attempts`, with
the kit's exponential backoff and a WARNING per retried failure). A statement is never
re-run.

## EXPLICIT\_DSN\_POOL\_MAX\_SIZE

`tai42_kit.clients.impl.postgres.EXPLICIT_DSN_POOL_MAX_SIZE`

```python theme={null}
EXPLICIT_DSN_POOL_MAX_SIZE: Final = 20
```

## EXPLICIT\_DSN\_POOL\_MIN\_SIZE

`tai42_kit.clients.impl.postgres.EXPLICIT_DSN_POOL_MIN_SIZE`

```python theme={null}
EXPLICIT_DSN_POOL_MIN_SIZE: Final = 1
```

## PostgresClient

`tai42_kit.clients.impl.postgres.PostgresClient`

```python theme={null}
class PostgresClient(PooledClient[_CancelSurfacingPool])
```

Pooled `psycopg_pool.AsyncConnectionPool`, one pool per DSN per loop.

The pool is named `<owner>@<host>/<db>`; `min_size`/`max_size` and
`retry_attempts` (re-attempts of the first connection's establishment) are this
database's deployment settings read when the pool is built; a second settings
prefix resolving to the same DSN with different values raises. Compose
`PostgresConnectionSettings` for the connection kwargs.

## open\_dedicated\_pool

`tai42_kit.clients.impl.postgres.open_dedicated_pool`

```python theme={null}
async open_dedicated_pool(
    target: PostgresConnectionSettings | str,
    *,
    role: str,
    connection_kwargs: dict[str, Any] | None = None,
    options: PostgresConnectionOptions | None = None,
) -> _CancelSurfacingPool
```

Open a dedicated (not shared) named pool for `role`, its first connection proven and its fill awaited.

A settings object supplies the DSN, the deployment's pool sizes and its
`pg_retry_attempts`; a DSN string gets `EXPLICIT_DSN_POOL_MIN_SIZE` /
`EXPLICIT_DSN_POOL_MAX_SIZE` and the behaviour of `options` (the caller's own
namespace; omitted means a single attempt). `options` with a settings object raises
`TypeError`: the settings carry their own. The pool is named
`postgres@<host>/<db>:<role>`; `connection_kwargs` apply to every connection it opens.
The caller owns the pool and closes it.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `target` | `PostgresConnectionSettings \| str` | — | — |
| `role` | `str` | — | — |
| `connection_kwargs` | `dict[str, Any] \| None` | `None` | — |
| `options` | `PostgresConnectionOptions \| None` | `None` | — |

## pinned\_connection

`tai42_kit.clients.impl.postgres.pinned_connection`

```python theme={null}
async pinned_connection(settings: PostgresConnectionSettings) -> AsyncIterator[AsyncConnection]
```

Yield one dedicated connection held for the whole context.

A one-connection pool (`min_size == max_size == 1`) built outside the shared
cache, named `<owner>@<host>/<db>:pinned`, opened through the same probe (with the
settings' `pg_retry_attempts`) and bounded fill as the pooled path. The caller
holds exactly one connection, so a session-scoped advisory lock taken on it covers
every statement in the body, and a driver error on it never touches the shared pool. The pool and its connection
close on any exit — normal return, exception, or cancellation.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `settings` | `PostgresConnectionSettings` | — | — |

## postgres\_pool\_name

`tai42_kit.clients.impl.postgres.postgres_pool_name`

```python theme={null}
postgres_pool_name(dsn: str, owner: str, role: str = '') -> str
```

The psycopg\_pool `name` for a database pool: `<owner>@<host>/<db>`.

Host and database come from the DSN via `conninfo_to_dict` — never the user
or password, which must not reach a pool name that surfaces in log lines. A
non-empty `role` appends a `:<role>` suffix so a dedicated pool (a pinned
connection, a langgraph store/checkpoint pool) is distinguishable in the logs.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `dsn` | `str` | — | — |
| `owner` | `str` | — | — |
| `role` | `str` | `''` | — |

## read\_connection

`tai42_kit.clients.impl.postgres.read_connection`

```python theme={null}
async read_connection(pool: AsyncConnectionPool[Any]) -> AsyncIterator[AsyncConnection[Any]]
```

A pooled connection in autocommit mode for stand-alone reads: each statement runs on its own, no BEGIN/COMMIT.

Plain SELECTs only. A locking read (FOR UPDATE / FOR SHARE), a write, or statements
that must be atomic together run on `pool.connection()` inside
`conn.transaction()`. The pool must be a `PostgresClient` pool, whose reset
callback returns the connection to transactional mode when it comes back.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `pool` | `AsyncConnectionPool[Any]` | — | — |


# Provider registration (tai42_kit.access_control, tai42_kit.accounts)
Source: https://docs.tai42.ai/reference/python-sdk/kit-registration

The identity-provider and accounts-provider registries a plugin registers into at import.

Module-level identity-provider registry — populated by direct import.

An identity plugin cannot register through the bound `tai42_app` handle: the plugin depends on
tai42-contract and tai42-kit only and bans `tai42_skeleton`, and `tai42_app` raises on ANY member
access before `bind()` runs (`bind()` runs only inside `start()`), so a handle-based registration
would crash at plugin import in any process that imports the plugin before `start()` — the metrics
entrypoint never calls `start()` at all. So the plugin imports this module and calls
`register_identity_provider` at its own module import. The registry is plain module state: it
fills in ANY process that imports the plugin module, with no `bind()` anywhere.

The registry stores FACTORIES, not descriptors: an identity provider is a live object holding a
store/connection, so a plugin registers a callable that builds the provider from settings. The
application drives the staging lifecycle; this module stays epoch-free.

## abort\_staging

`tai42_kit.access_control.registry.abort_staging`

```python theme={null}
abort_staging() -> None
```

Drop the staged generation on a failed build; a no-op when none is open.

## begin\_staging

`tai42_kit.access_control.registry.begin_staging`

```python theme={null}
begin_staging() -> None
```

Open a fresh staged generation an epoch build registers into; the committed one keeps serving.

## commit\_staging

`tai42_kit.access_control.registry.commit_staging`

```python theme={null}
commit_staging() -> None
```

Promote the staged generation in one reference assignment; a no-op when none is open.

## get\_identity\_provider\_factory

`tai42_kit.access_control.registry.get_identity_provider_factory`

```python theme={null}
get_identity_provider_factory(name: str) -> Callable[..., IdentityProvider]
```

Resolve a factory from the COMMITTED generation — the request-path accessor; `KeyError` when unknown.

**Parameters**

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

## get\_identity\_provider\_factory\_staged

`tai42_kit.access_control.registry.get_identity_provider_factory_staged`

```python theme={null}
get_identity_provider_factory_staged(name: str) -> Callable[..., IdentityProvider]
```

Resolve a factory from the STAGED generation while a build stages, else the committed one.

The build's own accessor (startup probe, kind status), so a build decides against the generation
it is assembling.

**Parameters**

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

## iter\_identity\_provider\_names\_staged

`tai42_kit.access_control.registry.iter_identity_provider_names_staged`

```python theme={null}
iter_identity_provider_names_staged() -> list[str]
```

Name-sorted names of the identity providers in the generation being resolved.

Reads the STAGED generation while a build stages, else the committed one. The derived default for
the access-control auth-provider chain: when no chain is configured, every registered identity
provider is resolved.

## register\_identity\_provider

`tai42_kit.access_control.registry.register_identity_provider`

```python theme={null}
register_identity_provider(name: str, factory: Callable[..., IdentityProvider]) -> None
```

Register a named identity-provider factory.

RELOAD-SAFE: re-registering the SAME factory (by `tai42_kit.registry.same_factory`) under a
name it already holds is a quiet no-op; a DIFFERENT factory under that name raises `ValueError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `factory` | `Callable[..., IdentityProvider]` | — | — |

## reset\_registry

`tai42_kit.access_control.registry.reset_registry`

```python theme={null}
reset_registry() -> None
```

Clear the write target — the staged generation while a build stages, else the committed one.

Module-level accounts-provider registry — populated by direct import.

Handle-free for the same reason as the identity-provider registry
(`tai42_kit.access_control.registry`): accounts plugins never import the application package and
register at plain module import, before any app handle is usable. The application resolves and
ACTIVATES providers from its own configuration — registration alone activates nothing.

Two differences from the identity registry:

* `register_accounts_provider` ALSO registers the factory into the identity registry under the
  same name — an accounts provider IS the token answerer for its own sessions, so registering into only
  one registry would make sessions mintable but not validatable (or vice versa). One plugin call, both
  registries, loud duplicate errors from either. The application stages and commits the two
  registries together.
* The registry is enumerable: the public login-methods aggregator asks EVERY registered accounts
  provider for its declared methods.

## abort\_staging

`tai42_kit.accounts.registry.abort_staging`

```python theme={null}
abort_staging() -> None
```

Drop the staged generation on a failed build; a no-op when none is open.

## begin\_staging

`tai42_kit.accounts.registry.begin_staging`

```python theme={null}
begin_staging() -> None
```

Open a fresh staged generation the epoch build registers into.

## commit\_staging

`tai42_kit.accounts.registry.commit_staging`

```python theme={null}
commit_staging() -> None
```

Promote the staged generation in one reference assignment; a no-op when none is open.

## get\_accounts\_provider\_factory

`tai42_kit.accounts.registry.get_accounts_provider_factory`

```python theme={null}
get_accounts_provider_factory(name: str) -> Callable[..., AccountsProvider]
```

The factory under `name` in the COMMITTED generation; `KeyError` when unknown.

**Parameters**

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

## iter\_accounts\_provider\_factories

`tai42_kit.accounts.registry.iter_accounts_provider_factories`

```python theme={null}
iter_accounts_provider_factories() -> list[tuple[str, Callable[..., AccountsProvider]]]
```

A fresh name-sorted snapshot of the COMMITTED factories.

## iter\_accounts\_provider\_factories\_staged

`tai42_kit.accounts.registry.iter_accounts_provider_factories_staged`

```python theme={null}
iter_accounts_provider_factories_staged() -> list[tuple[str, Callable[..., AccountsProvider]]]
```

A fresh name-sorted snapshot of the STAGED generation while a build stages, else the committed one.

The build's own accessor (the configured-providers boot check, kind status).

## register\_accounts\_provider

`tai42_kit.accounts.registry.register_accounts_provider`

```python theme={null}
register_accounts_provider(name: str, factory: Callable[..., AccountsProvider]) -> None
```

Register a named accounts-provider factory in BOTH registries.

RELOAD-SAFE: re-registering the SAME factory under a name it already holds is a quiet no-op in BOTH
registries; a DIFFERENT factory under a held name raises `ValueError`, in either registry. The
accounts no-op returns before touching the identity registry, and the identity registry is written
only when this name is new here (a refusal there leaves this registry untouched), so the two never
drift.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | — | — |
| `factory` | `Callable[..., AccountsProvider]` | — | — |

## reset\_registry

`tai42_kit.accounts.registry.reset_registry`

```python theme={null}
reset_registry() -> None
```

Clear the accounts write target only; the identity registry has its own lifecycle.


# Settings (tai42_kit.settings)
Source: https://docs.tai42.ai/reference/python-sdk/kit-settings

The base settings class and the settings registry.

Settings machinery: the base class, the cache-reset registry, and the owned-prefix audit.

Leaf settings live next to the impl they configure (`tai42_kit.llm`, `tai42_kit.clients`,
`tai42_kit.logging`).

## DEFAULT\_ENV\_FILE

`tai42_kit.settings.env_file.DEFAULT_ENV_FILE`

```python theme={null}
DEFAULT_ENV_FILE: Final = '.env'
```

## ENV\_IGNORE\_EMPTY

`tai42_kit.settings.base.ENV_IGNORE_EMPTY`

```python theme={null}
ENV_IGNORE_EMPTY: Final = True
```

## KUBERNETES\_SERVICE\_LINK\_SUFFIX\_RE

`tai42_kit.settings.owned_prefix.KUBERNETES_SERVICE_LINK_SUFFIX_RE`

```python theme={null}
KUBERNETES_SERVICE_LINK_SUFFIX_RE: Final = re.compile('^(SERVICE_HOST|SERVICE_PORT(_[A-Z0-9_]+)?|PORT(_[0-9]+_(TCP|UDP|SCTP)(_(PROTO|PORT|ADDR))?)?)$')
```

## TAI\_DEFAULT\_ENV\_PREFIX

`tai42_kit.settings.default_namespace.TAI_DEFAULT_ENV_PREFIX`

```python theme={null}
TAI_DEFAULT_ENV_PREFIX = 'TAI_DEFAULT_'
```

## DefaultNamespaceMixin

`tai42_kit.settings.default_namespace.DefaultNamespaceMixin`

```python theme={null}
class DefaultNamespaceMixin
```

Adds the `TAI_DEFAULT_*` per-field fallback to a settings class.

Declare `tai_default_fields` (`{field_name: default_key}`) on the subclass
to enable it. An empty map (the default) leaves the source pipeline untouched,
so a class that mixes this in without a map behaves as one that does not.

**Attributes**

| Attribute | Type |
| - | - |
| `tai_default_fields` | `Mapping[str, str]` |

### Members

#### settings\_customise\_sources

`tai42_kit.settings.default_namespace.DefaultNamespaceMixin.settings_customise_sources`

```python theme={null}
settings_customise_sources(
    cls,
    settings_cls: type,
    init_settings: PydanticBaseSettingsSource,
    env_settings: PydanticBaseSettingsSource,
    dotenv_settings: PydanticBaseSettingsSource,
    file_secret_settings: PydanticBaseSettingsSource,
) -> tuple[PydanticBaseSettingsSource, ...]
```

Append the `TAI_DEFAULT_*` fallback sources beneath the specific settings sources.

The specific sources are the next class's in the MRO (the settings base's,
whose dotenv slot holds the kit's cached dotenv source).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `settings_cls` | `type` | — | — |
| `init_settings` | `PydanticBaseSettingsSource` | — | — |
| `env_settings` | `PydanticBaseSettingsSource` | — | — |
| `dotenv_settings` | `PydanticBaseSettingsSource` | — | — |
| `file_secret_settings` | `PydanticBaseSettingsSource` | — | — |

## KeyMaterial

`tai42_kit.settings.base.KeyMaterial`

```python theme={null}
KeyMaterial = Annotated[SecretStr, Field(json_schema_extra={'key_material': True})]
```

## ReloadClass

`tai42_kit.settings.base.ReloadClass`

```python theme={null}
ReloadClass = Literal['hot', 'recycle', 'excluded']
```

## SettingsClassInfo

`tai42_kit.settings.registry.SettingsClassInfo`

```python theme={null}
class SettingsClassInfo(BaseModel)
```

A registered settings class, identified by its qualified name.

**Attributes**

| Attribute | Type |
| - | - |
| `name` | `str` |
| `module` | `str` |
| `qualname` | `str` |
| `fields` | `list[SettingsFieldInfo]` |
| `reload_class` | `ReloadClass` |
| `env_prefix` | `str` |
| `env_prefix_owned` | `bool` |

## SettingsFieldInfo

`tai42_kit.settings.registry.SettingsFieldInfo`

```python theme={null}
class SettingsFieldInfo(BaseModel)
```

One env-configurable field on a settings class, as plain data.

**Attributes**

| Attribute | Type |
| - | - |
| `name` | `str` |
| `env_var` | `str` |
| `type` | `str` |
| `default` | `Any \| None` |
| `required` | `bool` |
| `secret` | `bool` |
| `description` | `str \| None` |
| `nested_group` | `str \| None` |
| `default_namespace_var` | `str \| None` |
| `reload_class` | `ReloadClass` |
| `key_material` | `bool` |
| `accepted_env_vars` | `list[str]` |

## StaleHolder

`tai42_kit.settings.cache_registry.StaleHolder`

```python theme={null}
class StaleHolder
```

A still-live cached settings instance stamped with a retired epoch.

`settings_type` and `holders` are `module.qualname` strings (the settings
class, and the type of each object still referencing the instance).

**Attributes**

| Attribute | Type |
| - | - |
| `settings_type` | `str` |
| `epoch` | `int` |
| `holders` | `tuple[str, ...]` |

## TaiBaseSettings

`tai42_kit.settings.base.TaiBaseSettings`

```python theme={null}
class TaiBaseSettings(BaseSettings)
```

Base for env-configurable settings groups; concrete subclasses self-register.

A settings class reads the env file named by its `tai_env_file` class attribute
(default `.env`); the file is parsed once per file identity. A subclass that sets
`model_config['env_file']` is refused at import.

**Attributes**

| Attribute | Type |
| - | - |
| `model_config` | — |
| `tai_env_file` | `str \| Path \| None` |
| `reload_class` | `ReloadClass` |
| `env_prefix_owned` | `bool` |

### Members

#### settings\_customise\_sources

`tai42_kit.settings.base.TaiBaseSettings.settings_customise_sources`

```python theme={null}
settings_customise_sources(
    cls,
    settings_cls: type[BaseSettings],
    init_settings: PydanticBaseSettingsSource,
    env_settings: PydanticBaseSettingsSource,
    dotenv_settings: PydanticBaseSettingsSource,
    file_secret_settings: PydanticBaseSettingsSource,
) -> tuple[PydanticBaseSettingsSource, ...]
```

Put the kit's cached dotenv source in the dotenv slot.

The source reads `tai_env_file`, or no file when its reads are suspended
(`env_file_reads_suspended`). Every other option of
the source is read from `settings_cls.model_config`, as the framework's own source
reads it.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `settings_cls` | `type[BaseSettings]` | — | — |
| `init_settings` | `PydanticBaseSettingsSource` | — | — |
| `env_settings` | `PydanticBaseSettingsSource` | — | — |
| `dotenv_settings` | `PydanticBaseSettingsSource` | — | — |
| `file_secret_settings` | `PydanticBaseSettingsSource` | — | — |

#### with\_fallbacks

`tai42_kit.settings.base.TaiBaseSettings.with_fallbacks`

```python theme={null}
with_fallbacks(self, user_config: dict) -> dict
```

Return a dict with defaults added for missing keys (never override user config).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `user_config` | `dict` | — | — |

#### load\_with\_fallbacks

`tai42_kit.settings.base.TaiBaseSettings.load_with_fallbacks`

```python theme={null}
load_with_fallbacks(self, user_config: str) -> dict
```

Parse `user_config` JSON (or empty) and merge it over the defaults.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `user_config` | `str` | — | — |

## UnknownOwnedSettingError

`tai42_kit.settings.owned_prefix.UnknownOwnedSettingError`

```python theme={null}
class UnknownOwnedSettingError(ValueError)
```

An env name under an owned settings prefix names no registered setting.

## bind\_respawn\_class\_env

`tai42_kit.settings.registry.bind_respawn_class_env`

```python theme={null}
bind_respawn_class_env() -> None
```

Bind every registered respawn-class env var to the value the settings layer reads for it now.

Called once a lifespan applied its env, before it builds the resources behind those values:
a group registered later binds its own vars at its registration. Overwrites every value an
earlier bind recorded.

## changes\_only\_by\_respawn

`tai42_kit.settings.registry.changes_only_by_respawn`

```python theme={null}
changes_only_by_respawn(cls: type[BaseSettings]) -> bool
```

Whether every value of the registered settings group `cls` changes only by a process respawn or restart.

True when `cls` is registered and every field's reload class is `recycle` or
`excluded`; a field that references a nested group is judged by that group's own
registered fields, recursively. False for an unregistered class (a plain
`BaseSettings`, a `registry_exclude` base, a class with no fields), for a nested
group that is unregistered or references back into the groups being judged, and
for any `hot` field.

## env\_file\_identity

`tai42_kit.settings.env_file.env_file_identity`

```python theme={null}
env_file_identity(path: str | os.PathLike[str]) -> EnvFileIdentity | None
```

The identity of the regular file at `path`, or `None` when there is none.

A missing path, a directory, a FIFO, or a path `stat` cannot reach answers
`None`, as `Path.is_file()` answers `False` for each.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `str \| os.PathLike[str]` | — | — |

## env\_file\_reads\_suspended

`tai42_kit.settings.env_file.env_file_reads_suspended`

```python theme={null}
env_file_reads_suspended(path: str | os.PathLike[str]) -> Iterator[None]
```

Read the env file at `path` in no settings construction inside the block.

`path` is resolved on entry (a relative path against the working directory, symlinks
followed), and a settings class whose env file resolves to the same file reads no env
file inside the block; an env file at any other path is still read. Blocks nest, each
adding its path. The state is held in a context variable: a task created inside the
block copies the context and so skips the file too, while a thread started with
`threading.Thread` starts from an empty context and reads it, unless the interpreter
makes threads inherit the context (`sys.flags.thread_inherit_context`).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `str \| os.PathLike[str]` | — | — |

## is\_kubernetes\_service\_link

`tai42_kit.settings.owned_prefix.is_kubernetes_service_link`

```python theme={null}
is_kubernetes_service_link(key: str, names: frozenset[str]) -> bool
```

True when the upper-cased `key` is `<NAME>_<suffix>` for a `<NAME>` in `names`.

`<suffix>` must match `KUBERNETES_SERVICE_LINK_SUFFIX_RE`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `key` | `str` | — | — |
| `names` | `frozenset[str]` | — | — |

## keyed\_settings\_cache

`tai42_kit.settings.cache_registry.keyed_settings_cache`

```python theme={null}
keyed_settings_cache(fn: Callable[[K], V]) -> Callable[[K], V]
```

Cache a one-argument settings accessor per key, cleared on reset and re-read when the env file changes.

An entry is served while the env file keeps the identity it had when the entry
was built; `reset_all_settings()` drops every entry. A settings instance is
epoch-stamped on construction like `settings_cache`'s. A build that raises
stores nothing, so the next call builds again. One accessor exists per qualified name,
re-bound by a re-import exactly as `settings_cache`'s.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `fn` | `Callable[[K], V]` | — | — |

## kubernetes\_service\_link\_names

`tai42_kit.settings.owned_prefix.kubernetes_service_link_names`

```python theme={null}
kubernetes_service_link_names(environ: Mapping[str, str]) -> frozenset[str]
```

The `<NAME>` of every Service whose link family is present in `environ`.

Empty unless `KUBERNETES_SERVICE_HOST` is in `environ`. Otherwise each `<NAME>`
for which BOTH `<NAME>_SERVICE_HOST` and `<NAME>_PORT` are in `environ` (keys
compared upper-cased).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `environ` | `Mapping[str, str]` | — | — |

## not\_configured\_message

`tai42_kit.settings.require.not_configured_message`

```python theme={null}
not_configured_message(subject: str, env_var: str, default_var: str | None = None) -> str
```

The named-error message for an unset connection setting.

`default_var` is the field's `TAI_DEFAULT_*` alternative, named in the
message when the field participates in the shared namespace; omit it for a
field that only its own env var can set.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `subject` | `str` | — | — |
| `env_var` | `str` | — | — |
| `default_var` | `str \| None` | `None` | — |

## owned\_env\_prefixes

`tai42_kit.settings.owned_prefix.owned_env_prefixes`

```python theme={null}
owned_env_prefixes() -> frozenset[str]
```

Every env prefix a registered group declares owned.

## present\_env\_value

`tai42_kit.settings.base.present_env_value`

```python theme={null}
present_env_value(env: Mapping[str, str], var: str) -> str | None
```

The value the settings layer reads for `var`: `None` when absent or empty, the kit's empty-is-absent rule.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `env` | `Mapping[str, str]` | — | — |
| `var` | `str` | — | — |

## refuse\_unknown\_owned\_env

`tai42_kit.settings.owned_prefix.refuse_unknown_owned_env`

```python theme={null}
refuse_unknown_owned_env(
    keys: Iterable[str],
    *,
    source: str,
    service_link_env: Mapping[str, str] | None = None,
) -> None
```

Raise `UnknownOwnedSettingError` naming every unknown key; no-op when none.

`source` names where the keys were read (it leads the message).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `keys` | `Iterable[str]` | — | — |
| `source` | `str` | — | — |
| `service_link_env` | `Mapping[str, str] \| None` | `None` | — |

## register\_settings\_reset

`tai42_kit.settings.cache_registry.register_settings_reset`

```python theme={null}
register_settings_reset(fn: Callable[[], None]) -> Callable[[], None]
```

Register a hook that resets settings-derived state on global reset.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `fn` | `Callable[[], None]` | — | — |

## registered\_settings

`tai42_kit.settings.registry.registered_settings`

```python theme={null}
registered_settings() -> list[SettingsClassInfo]
```

Snapshot of every registered settings group, in registration order.

Returns model copies so callers cannot mutate the registry's internals.

## require

`tai42_kit.settings.require.require`

```python theme={null}
require(value: T | None, subject: str, env_var: str, default_var: str | None = None) -> T
```

The configured `value`, or raise the named error when it is `None`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `T \| None` | — | — |
| `subject` | `str` | — | — |
| `env_var` | `str` | — | — |
| `default_var` | `str \| None` | `None` | — |

## require\_secret

`tai42_kit.settings.require.require_secret`

```python theme={null}
require_secret(
    value: SecretStr | None,
    subject: str,
    env_var: str,
    default_var: str | None = None,
) -> str
```

The secret's plaintext, or raise on unset OR empty — fail CLOSED.

A secret that gates a trust boundary must not be satisfiable by an empty
value, so both the unset and the empty cases raise.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `SecretStr \| None` | — | — |
| `subject` | `str` | — | — |
| `env_var` | `str` | — | — |
| `default_var` | `str \| None` | `None` | — |

## reset\_all\_settings

`tai42_kit.settings.cache_registry.reset_all_settings`

```python theme={null}
reset_all_settings() -> None
```

Drop every registered settings cache, then run the reset hooks.

## respawn\_class\_env\_drift

`tai42_kit.settings.registry.respawn_class_env_drift`

```python theme={null}
respawn_class_env_drift() -> frozenset[str]
```

The bound respawn-class env vars whose value the settings layer reads now differs from the bound one.

Such a value takes effect only in a respawned process. Empty while nothing is bound.

## restamp\_settings\_born\_after

`tai42_kit.settings.cache_registry.restamp_settings_born_after`

```python theme={null}
restamp_settings_born_after(mark: int) -> None
```

Stamp every live settings instance constructed after `mark` with the current epoch.

A serving generation built off to the side reads its settings while the epoch it
will serve under is not yet current, so those instances carry the epoch it
replaces. Once its epoch is current, the builder re-stamps everything constructed
since the mark it took when the build began: a sweep of the replaced epoch then
judges only the instances read before the build, and the new generation's own
instances are judged when its epoch retires.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `mark` | `int` | — | — |

## settings\_birth\_mark

`tai42_kit.settings.cache_registry.settings_birth_mark`

```python theme={null}
settings_birth_mark() -> int
```

The birth number of the most recently stamped settings instance (0 before any).

Every instance stamped after this call has a larger birth number, so the mark
separates what was constructed before it from what is constructed after it
(see `restamp_settings_born_after`).

## settings\_cache

`tai42_kit.settings.cache_registry.settings_cache`

```python theme={null}
settings_cache(fn: F) -> F
```

Cache a zero-arg settings accessor, register it for reset, and epoch-stamp it.

Stamping happens on the CONSTRUCTION path (cache miss), so the stamp records
the epoch the instance was born under; a cached hit returns the same stamped
instance, and a reset clears the cache so the next call rebuilds and re-stamps
under the then-current epoch.

One accessor exists per qualified name: decorating a function whose name is already
registered (a module re-import) re-binds that accessor to the new function, clears its
cache and returns the same wrapper.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `fn` | `F` | — | — |

## sweep\_stale\_settings

`tai42_kit.settings.cache_registry.sweep_stale_settings`

```python theme={null}
sweep_stale_settings(retired_epoch: int) -> list[StaleHolder]
```

Report every settings instance stamped with `retired_epoch` that something still holds.

The roster holds only settings whose values can change within the process, so
the sweep judges only those. Walks the roster for instances whose stamp is the retired epoch and are still
alive. When any is found, cyclic garbage is collected first, so an instance
that only unreachable objects keep (the finished frame of a cancelled task
awaiting collection) is freed rather than reported. Each instance still alive
after that is reachable, which is a stale-config leak: it is logged at ERROR
naming its holders (a referrer's type, or the function and `file:line` of a
frame or coroutine that keeps it) and returned, so a probe/e2e can assert zero.
Nothing is dropped.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `retired_epoch` | `int` | — | — |

## unbind\_respawn\_class\_env

`tai42_kit.settings.registry.unbind_respawn_class_env`

```python theme={null}
unbind_respawn_class_env() -> None
```

Drop the bound respawn-class env (a lifespan's end); nothing is bound until the next bind.

## unknown\_owned\_env\_keys

`tai42_kit.settings.owned_prefix.unknown_owned_env_keys`

```python theme={null}
unknown_owned_env_keys(keys: Iterable[str], *, service_link_env: Mapping[str, str] | None = None) -> list[tuple[str, str]]
```

`(key, prefix)` for each key under an owned prefix that no registered group accepts, sorted by key.

Comparison is upper-cased; the accepted set is the union of `accepted_env_vars` of every
registered group (any prefix), so an alias declared elsewhere is accepted. A key under
several owned prefixes is reported with the longest. With `service_link_env` (the
process environment), an unaccepted key for which
`is_kubernetes_service_link(key, kubernetes_service_link_names(service_link_env))` holds
is not reported: the container runtime injects a Service's link family into every pod of
its namespace, and a Service named like an owned prefix yields names under it. A lone
`<NAME>_PORT` or `<NAME>_SERVICE_HOST`, or any key outside a Kubernetes pod, is
reported like any unknown name.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `keys` | `Iterable[str]` | — | — |
| `service_link_env` | `Mapping[str, str] \| None` | `None` | — |


# Transports (tai42_kit.transport)
Source: https://docs.tai42.ai/reference/python-sdk/kit-transport

UDS transports and the MCP transport factory.

MCP client transports over a unix-domain socket + the transport selector.

The UDS transports implement the contract `Transport` Protocol; `get_mcp_transport`
picks between them, fastmcp's remote transports for URL servers, or a plain
dict-config for command servers.

## BaseUDSTransport

`tai42_kit.transport.base_uds_transport.BaseUDSTransport`

```python theme={null}
class BaseUDSTransport(ClientTransport)
```

MCP client transport that connects over a Unix domain socket at `socket_path`.

**Attributes**

| Attribute | Type |
| - | - |
| `socket_path` | — |

## HTTPUDSTransport

`tai42_kit.transport.http_uds_transport.HTTPUDSTransport`

```python theme={null}
class HTTPUDSTransport(BaseUDSTransport)
```

MCP transport speaking streamable-HTTP over a Unix domain socket.

### Members

#### connect\_session

`tai42_kit.transport.http_uds_transport.HTTPUDSTransport.connect_session`

```python theme={null}
async connect_session(self, **session_kwargs: Any) -> AsyncGenerator[ClientSession]
```

Open an MCP client session over the socket, yielding it for the block.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `session_kwargs` | `Any` | `{}` | — |

## SSEUDSTransport

`tai42_kit.transport.sse_uds_transport.SSEUDSTransport`

```python theme={null}
class SSEUDSTransport(BaseUDSTransport)
```

MCP client transport that speaks Server-Sent Events over a Unix domain socket.

### Members

#### connect\_session

`tai42_kit.transport.sse_uds_transport.SSEUDSTransport.connect_session`

```python theme={null}
async connect_session(self, **session_kwargs: Any) -> AsyncGenerator[ClientSession]
```

Open an MCP client session over the socket's SSE endpoint.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `session_kwargs` | `Any` | `{}` | — |

## get\_mcp\_transport

`tai42_kit.transport.utils.get_mcp_transport`

```python theme={null}
get_mcp_transport(config: TaiMCPConfig, *, uds_protocol: str = 'http') -> HTTPUDSTransport | SSEUDSTransport | StreamableHttpTransport | SSETransport | dict[str, Any]
```

Build the fastmcp transport for one MCP server config.

A UDS server connects over a unix socket; `uds_protocol` selects the MCP
wire protocol carried on it (`http` = streamable-http, `sse` = SSE) — the
caller (which owns the runtime/CLI) supplies it, so it arrives unvalidated and
any other value raises. A URL server gets fastmcp's SSE or streamable-http
transport, chosen by fastmcp's own URL inference, carrying only the config's
headers and built on `mcp_http_client`; it ignores `uds_protocol`. A
command server returns a plain fastmcp dict-config.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `config` | `TaiMCPConfig` | — | — |
| `uds_protocol` | `str` | `'http'` | — |


# Skeleton app (tai42_skeleton.app)
Source: https://docs.tai42.ai/reference/python-sdk/skeleton-app

The concrete TaiMCP app, including the raw fastmcp escape hatch.

The concrete `tai42_contract.app.TaiApp` server (`TaiMCP`).

## TaiMCP

`tai42_skeleton.app.server.TaiMCP`

```python theme={null}
class TaiMCP(TaiMCPLifecycleMixin)
```

The concrete `tai42_contract.app.TaiApp` impl — owns the FastMCP server.

Exposes the contract facet namespaces as its SOLE feature/contract surface;
the concrete server additionally exposes a launch surface (`sse_app` /
`http_app` / `run` and friends) that is not part of the facade.

This class is the composition root only: each feature's impl body lives in
its feature package (`tools.binding.ToolBinding`, `agent.binding
.AgentBinding`, `backend.registry.BackendHolder`, the extension/monitoring
registries, `app.http.HttpSurface`) and each facet forwards straight to its
collaborator. Callers reach the app's features only through the facets
(`app.tools.run_tool`, `app.backends.backend`, ...) or the `tai42_app`
handle, never a flat member.

### Members

#### tools

`tai42_skeleton.app.server.TaiMCP.tools`

```python theme={null}
tools: ToolsFacet
```

The tool/toolkit registration, lookup, and execution facet (`app.tools`).

#### agents

`tai42_skeleton.app.server.TaiMCP.agents`

```python theme={null}
agents: AgentsFacet
```

The agent registration and run-binding facet (`app.agents`).

#### backends

`tai42_skeleton.app.server.TaiMCP.backends`

```python theme={null}
backends: BackendsFacet
```

The background-execution backend facet (`app.backends`).

#### sandboxes

`tai42_skeleton.app.server.TaiMCP.sandboxes`

```python theme={null}
sandboxes: SandboxesFacet
```

The sandbox-provider facet (`app.sandboxes`).

#### storage

`tai42_skeleton.app.server.TaiMCP.storage`

```python theme={null}
storage: StorageFacet
```

The resource-storage facet (`app.storage`).

#### connectors

`tai42_skeleton.app.server.TaiMCP.connectors`

```python theme={null}
connectors: ConnectorsFacet
```

The connector registration and credential-resolution facet (`app.connectors`).

#### interactions

`tai42_skeleton.app.server.TaiMCP.interactions`

```python theme={null}
interactions: InteractionsFacet
```

The interactions facet (`app.interactions`) — the `ask` facade.

#### accounts

`tai42_skeleton.app.server.TaiMCP.accounts`

```python theme={null}
accounts: AccountsFacet
```

The identity/accounts provider facet (`app.accounts`).

#### webhook\_verifiers

`tai42_skeleton.app.server.TaiMCP.webhook_verifiers`

```python theme={null}
webhook_verifiers: WebhookVerifiersFacet
```

The webhook-verifier registration facet (`app.webhook_verifiers`).

#### channels

`tai42_skeleton.app.server.TaiMCP.channels`

```python theme={null}
channels: ChannelsFacet
```

The channel registration facet (`app.channels`).

#### conversations

`tai42_skeleton.app.server.TaiMCP.conversations`

```python theme={null}
conversations: ConversationsFacet
```

The conversation-bridge facet (`app.conversations`).

#### media

`tai42_skeleton.app.server.TaiMCP.media`

```python theme={null}
media: MediaFacet
```

The served-media ingestion facet (`app.media`).

#### monitoring

`tai42_skeleton.app.server.TaiMCP.monitoring`

```python theme={null}
monitoring: MonitoringFacet
```

The monitoring-backend facet (`app.monitoring`).

#### extensions

`tai42_skeleton.app.server.TaiMCP.extensions`

```python theme={null}
extensions: ExtensionsFacet
```

The extension registration facet (`app.extensions`).

#### http

`tai42_skeleton.app.server.TaiMCP.http`

```python theme={null}
http: HttpFacet
```

The custom HTTP route facet (`app.http`).

#### clients

`tai42_skeleton.app.server.TaiMCP.clients`

```python theme={null}
clients: ClientsFacet
```

The pooled-client lifecycle facet (`app.clients`).

#### lifecycle

`tai42_skeleton.app.server.TaiMCP.lifecycle`

```python theme={null}
lifecycle: LifecycleFacet
```

The startup/shutdown/reload lifecycle facet (`app.lifecycle`).

#### admin

`tai42_skeleton.app.server.TaiMCP.admin`

```python theme={null}
admin: AdminFacet
```

The in-process admin-operations facet (`app.admin`).

#### config

`tai42_skeleton.app.server.TaiMCP.config`

```python theme={null}
config: ConfigFacet
```

The process config-manager facet (`app.config`).

#### sub\_app

`tai42_skeleton.app.server.TaiMCP.sub_app`

```python theme={null}
sub_app: SubAppFacet
```

The sub-app MCP router facet (`app.sub_app`).

#### backup

`tai42_skeleton.app.server.TaiMCP.backup`

```python theme={null}
backup: BackupFacet
```

The backup-section facet (`app.backup`).

#### versioning

`tai42_skeleton.app.server.TaiMCP.versioning`

```python theme={null}
versioning: VersioningFacet
```

The versioned-document store facet (`app.versioning`).

#### presets

`tai42_skeleton.app.server.TaiMCP.presets`

```python theme={null}
presets: PresetsFacet
```

The presets facet (`app.presets`).

#### states

`tai42_skeleton.app.server.TaiMCP.states`

```python theme={null}
states: StatesFacet
```

The subject-keyed state store facet — the `tai42_contract.app.AppStates` namespace.

#### tool\_meta

`tai42_skeleton.app.server.TaiMCP.tool_meta`

```python theme={null}
tool_meta: ToolMetaFacet
```

The tool-metadata overlay facet — the `tai42_contract.app.AppToolMeta` namespace.

The organizational overlay (folders + per-tool rows) over any live tool.

#### fastmcp

`tai42_skeleton.app.server.TaiMCP.fastmcp`

```python theme={null}
fastmcp: FastMCP
```

The raw, ungoverned FastMCP server — the escape hatch beneath the facets.

Prefer the facets; reach here only for what the facets don't wrap
(prompts, resources, `add_middleware`, sampling, elicit-handlers,
completions, server metadata such as `name`/`version`/`auth`, the
process-global `fastmcp.settings`). Anything registered THROUGH this
server skips the platform's governance: manifest gating, the extension
registry's `validate()`, and the access-control gate. It is
deliberately NOT on the `tai42_contract.app.TaiApp` protocol — the
contract stays FastMCP-free so an alternative impl remains possible, so
this accessor is skeleton-specific.

Named `fastmcp` (not `mcp`) because `app.sub_app` already owns the
sub-MCP namespace; `mcp` here would read as the sub-MCP.

#### emit\_list\_changed

`tai42_skeleton.app.server.TaiMCP.emit_list_changed`

```python theme={null}
async emit_list_changed(self, kind: str) -> None
```

Broadcast a `list_changed` notification to every active MCP session for the given registry `kind`.

`kind` is SINGULAR (`tool` / `prompt` / `resource`). The generic in-process
registration-mutation path (e.g. a dev's runtime `add_prompt` via `app.fastmcp`) awaits
this after its own registry mutation; the reload path drives the same registry from its
sync scheduler.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `str` | — | — |

#### sse\_app

`tai42_skeleton.app.server.TaiMCP.sse_app`

```python theme={null}
sse_app(
    self,
    path: str | None = None,
    message_path: str | None = None,
    middleware: list[Middleware] | None = None,
) -> StarletteWithLifespan
```

Build the SSE ASGI app for this server, recording the served SSE surface.

The message endpoint is mounted and announced with a trailing slash (a supplied
`message_path` gains one): the mount matches the announced address, so no message is
redirected to an absolute address a TLS-ending proxy would rewrite.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `str \| None` | `None` | — |
| `message_path` | `str \| None` | `None` | — |
| `middleware` | `list[Middleware] \| None` | `None` | — |

#### http\_app

`tai42_skeleton.app.server.TaiMCP.http_app`

```python theme={null}
http_app(
    self,
    path: str | None = None,
    middleware: list[Middleware] | None = None,
    json_response: bool | None = None,
    stateless_http: bool | None = None,
    transport: Literal['http', 'streamable-http', 'sse'] = 'http',
) -> StarletteWithLifespan
```

Build the streamable-HTTP (or SSE) ASGI app for this server, recording the served surface.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `str \| None` | `None` | — |
| `middleware` | `list[Middleware] \| None` | `None` | — |
| `json_response` | `bool \| None` | `None` | — |
| `stateless_http` | `bool \| None` | `None` | — |
| `transport` | `Literal['http', 'streamable-http', 'sse']` | `'http'` | — |

#### run\_async

`tai42_skeleton.app.server.TaiMCP.run_async`

```python theme={null}
async run_async(
    self,
    transport: Transport | None = None,
    show_banner: bool = True,
    **transport_kwargs: Any,
) -> None
```

Run the FastMCP server asynchronously over `transport`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `transport` | `Transport \| None` | `None` | — |
| `show_banner` | `bool` | `True` | — |
| `transport_kwargs` | `Any` | `{}` | — |

#### run

`tai42_skeleton.app.server.TaiMCP.run`

```python theme={null}
run(
    self,
    transport: Transport | None = None,
    show_banner: bool = True,
    **transport_kwargs: Any,
) -> None
```

Run the FastMCP server (blocking) over `transport`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `transport` | `Transport \| None` | `None` | — |
| `show_banner` | `bool` | `True` | — |
| `transport_kwargs` | `Any` | `{}` | — |

#### run\_backend

`tai42_skeleton.app.server.TaiMCP.run_backend`

```python theme={null}
async run_backend(self, args) -> None
```

Launch the background-execution backend with `args`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `args` | — | — | — |

#### preset\_manager

`tai42_skeleton.app.server.TaiMCP.preset_manager`

```python theme={null}
preset_manager: PresetManager
```

The preset register/reload engine (spec map + quarantine set + register/reload/remove/rehydrate).

Skeleton-only surface — like `emit_list_changed` and `fastmcp`, it is deliberately not on
the `tai42_contract.app.TaiApp` protocol; the preset routes and the startup/reload
rehydration hook reach it through this concrete instance.


# ASGI factory (tai42_skeleton.asgi)
Source: https://docs.tai42.ai/reference/python-sdk/skeleton-asgi

The public create_app factory for embedding the server in a user-owned ASGI process.

Public ASGI application factory for a user-owned tai server process.

`create_app` is the programmatic entry point for embedding the tai MCP
application inside a host-owned ASGI process — a plain `uvicorn main:app` run or
a mount inside an existing FastAPI/Starlette host:

```python theme={null}
from tai42_skeleton.asgi import create_app

app = create_app(manifest_path="manifest.yml")
```

The returned Starlette app carries the full worker lifespan (manifest load,
`app_context`, transport selection, and the inner FastMCP lifespan), so the host
serves it exactly as the runtime CLI serves its own workers.

One app per process. The `tai42_app` contract handle and the built app are
process-global singletons, so a second `create_app` lifespan entered while one
is already active raises loudly rather than silently rebinding the handle;
sequential lifespans in one process (enter -> exit -> enter) stay legal.

Deliberately CLI-owned and absent here: root-logger configuration (an embedded
app never touches the host's logging), the Prometheus multiprocess metrics
environment (the embedded app serves its own in-app `/metrics` route in
IN-PROCESS mode, rendering this process's default registry; it does not set up the
MULTIPROCESS dir — a separate reader over a shared multiproc dir is yours to run),
and process-fleet orchestration. Fleet config-reload fan-out is the app's internal
worker bus: an embedded worker joins it like any other process when
`TAI_BUS_REDIS_URL` is set (the rules cannot count sibling processes in an
embedded host, so set it in any multi-process embed). Sub-MCP registrations are
shared across processes only through their own store, so a multi-process embed also
sets `SUB_MCP_REDIS_URL` (or `TAI_DEFAULT_REDIS_URL`), and hooks likewise through
`HOOKS_REDIS_URL` (or `TAI_DEFAULT_REDIS_URL`). The lifespan's workers-need-bus and
workers-need-stores rules read the worker count `tai serve` stamps in `TAI_SERVE_WORKERS`; an embedded
host does not set it, so each process counts as one worker and those rules never
refuse here. The lifespan refuses a manifest that registers a task backend over an
in-memory hooks registry at any process count.

## Transport

`tai42_skeleton.asgi.Transport`

```python theme={null}
Transport = Literal['http', 'streamable-http', 'sse']
```

## create\_app

`tai42_skeleton.asgi.create_app`

```python theme={null}
create_app(
    manifest_path: str | None = None,
    *,
    transport: Transport = 'http',
    stateless_http: bool = False,
) -> Starlette
```

Build the public ASGI app for a user-owned process.

One app per process: the returned app's lifespan claims a process-global
one-app token, and a second lifespan entered while one is active raises. The
`transport` and `stateless_http` arguments are validated at call time.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `manifest_path` | `str \| None` | `None` | The manifest this app loads. Omit it to let the existing environment / config-dir resolution apply. |
| `transport` | `Transport` | `'http'` | The MCP transport to serve. |
| `stateless_http` | `bool` | `False` | Run an http/streamable-http transport in fastmcp's stateless mode. Has no `sse` equivalent, so pairing it with the `sse` transport is rejected at call time. |

**Returns** — A Starlette app whose lifespan claims the one-app token, stamps the manifest env, builds the app singleton, enters `app_context` and the inner FastMCP lifespan, and releases the token (restoring the env) on exit.

## lifespan

`tai42_skeleton.asgi.lifespan`

```python theme={null}
lifespan(app: Starlette)
```

Return a `create_app` app's lifespan context manager for composing into a host lifespan.

Mounting the factory app is not enough on its own: Starlette does not run a
mounted sub-app's lifespan, so the host must run it. Enter the returned context
manager inside the host's own lifespan so the tai app's worker startup (manifest
load, `app_context`, transport selection, the inner FastMCP lifespan) runs for
the host process's lifetime.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `app` | `Starlette` | — | A `create_app` result whose lifespan the host runs. |

**Returns** — The app's lifespan context manager (`app.router.lifespan_context(app)`), to be entered inside the host lifespan.


# State record validation (tai42_skeleton.states)
Source: https://docs.tai42.ai/reference/python-sdk/skeleton-states

The store-free record validator, the effective-schema composer, and the state-template document validator.

Static validity of a state's JSON-Schema and its stored document.

The pure draft 2020-12 validators the template document parser and the states service
both lean on: an object-rooted schema check, the document rules every schema a record or a
value is validated against holds (`check_document_rules`), full-document validation
against an effective schema, and the conservative narrowing comparison two schemas are
compared with. `RecordValidator` is the public face over these validators for a caller
with no store bound. Depends only on the standard library, `jsonschema`/`referencing`, the
kit's JSON Schema rules and the contract's states models.

## RecordValidator

`tai42_skeleton.states.schema.RecordValidator`

```python theme={null}
class RecordValidator
```

Validates record documents against one schema, as a write to a declared state would.

For a caller with no store bound (a test, a check before a deploy): give it the schema a
record is validated WHOLE against — a declared state's effective schema (the base schema
with its attachments composed in) — and call `validate` per document. The schema is
checked once at construction by the same rules a declaration is (object-rooted, at least
one property, and `check_document_rules`), and refused loudly with
`SchemaValidationError`; the compiled validator is
then reused for every document. A by-id schema is resolved by the caller first.

### Members

#### validate

`tai42_skeleton.states.schema.RecordValidator.validate`

```python theme={null}
validate(self, data: Any) -> RecordValidation
```

EVERY way `data` misfits the schema, ordered by JSON path; `fits` when there is none.

A non-object `data` raises `ValueValidationError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `data` | `Any` | — | — |

## check\_document\_rules

`tai42_skeleton.states.schema.check_document_rules`

```python theme={null}
check_document_rules(schema: Any, *, subject: str) -> None
```

Refuse a schema a draft 2020-12 validator could not check a document against, naming the fault.

The JSON Schema rules are the kit's
(`check_schema_rules` with
`Draft202012Validator`): the meta-schema, compiling `pattern` and
`patternProperties` regexes, finite numbers, one resource (no root `$id` naming a
meta-schema, no `$id` below the root, unique anchor names, and, under a root `$id`, no
`$dynamicAnchor` below the root whose name the meta-schema subschema a reference reaches binds
dynamically or the reference names), every reference
resolving inside the schema or into a meta-schema (none is fetched), every pointer indexing an
array with an RFC 6901 index, and no cycle of references that never descends into the
document. On top of them, a
states document is one draft 2020-12 dialect without dynamic references: a `$schema` naming
another dialect, or a `$dynamicRef`, anywhere among the subschemas validation evaluates
(`evaluated_subschemas`: under every applicator
and at every reference target, whatever form the reference takes) is refused. `subject`
opens the message (`"state schema"`, a template's value-schema place). Every refusal raises
`SchemaValidationError`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `schema` | `Any` | — | — |
| `subject` | `str` | — | — |

## iter\_refs

`tai42_skeleton.states.schema.iter_refs`

```python theme={null}
iter_refs(node: Any)
```

Yield the `$ref` string of every node of the schema document's `schema_nodes`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `node` | `Any` | — | — |

## schema\_nodes

`tai42_skeleton.states.schema.schema_nodes`

```python theme={null}
schema_nodes(root: dict[str, Any]) -> list[dict[str, Any]]
```

`root`'s subschemas and every node a `#/…` pointer ref among them reaches, each once.

`root`'s subschemas (`_subschemas`), closed over the target of every `#/…` pointer
ref among them (an absolute ref is not followed): jsonschema evaluates a pointer's target as a
schema wherever it sits (under an unknown or a data keyword too) and follows the refs inside
it, so the target's subschemas join the set, to a fixpoint (a node already in the set is not
walked again, so cyclic refs end). Each pointer is resolved against `root`; one that does
not resolve raises `SchemaValidationError`. A target outside the subschema positions —
which `root`'s own `check_schema` does not cover — is checked once as a draft 2020-12
schema, so the walk stays linear in the schema's size and its ref count.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `root` | `dict[str, Any]` | — | — |

Composing attached fragments into the effective schema.

Each attachment's substituted (and, when the template traces, `_trace`-stamped) fragment
is placed into a base schema at its path, refusing collisions and overlapping attach paths.
A fragment placed at a path has its `#` and `#/…` references rebased to that path, so
they keep resolving against the fragment; a fragment attached at the root merges its
`properties`, `required` and `$defs` into the root and may carry no other validating
root keyword, nor a pointer reference outside its `properties` and `$defs`. The
composed schema is checked by the declaration rules before it is returned.

## compose\_effective\_schema

`tai42_skeleton.states.templates.compose.compose_effective_schema`

```python theme={null}
compose_effective_schema(
    base_schema: dict[str, Any],
    attachments: Sequence[tuple[StateTemplate, list[str], Mapping[str, Any]]],
) -> dict[str, Any]
```

The base schema with each attachment's fragment placed at its path.

Each attachment is `(template, path, parameters)`: the template's fragment is
substituted with `defaults` overlaid by `parameters` (an unsupplied no-default
marker is a loud refusal), `_trace`-stamped when the template traces, and placed at
`path` — creating intermediate `{"type": "object", "properties": {}}` levels. At a
non-empty path every `#` / `#/…` `$ref` in the fragment is rebased to the placement
pointer (`#/properties/<seg>/…`), so it resolves inside the fragment as it did alone;
`#anchor` refs are left as they are. At the root path the fragment's root `type` must
be `object`; its `properties`, `required` and `$defs` are merged into the base
root, its annotation keywords are dropped, and any other root keyword is refused, as is a
`#` / `#/…` ref outside the fragment's `properties` and `$defs`. An attachment
path that collides with an existing base property, a root `$defs` key that collides with
the base's, a root type, keyword or ref that cannot be merged, or an attach path
overlapping another attachment's path, is refused with
`AttachConflictError`. A fragment its parameters leave
malformed is refused with `SchemaValidationError`
naming the template. The composed schema satisfies the declaration rules (object-rooted, at
least one property, a valid draft 2020-12 schema, no `$schema` naming another dialect, every
`$ref` local and resolvable, no `$dynamicRef`, no root `$id` naming a meta-schema, no
`$id` below the root, unique `$anchor` / `$dynamicAnchor` names, under a root `$id` no
`$dynamicAnchor` below the root whose name the meta-schema subschema a reference reaches binds
dynamically or the reference names, every pointer's array index an RFC 6901 index, no cycle of
references that never descends into the document), raising
`SchemaValidationError` otherwise.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `base_schema` | `dict[str, Any]` | — | — |
| `attachments` | `Sequence[tuple[StateTemplate, list[str], Mapping[str, Any]]]` | — | — |

The platform state-template document parser and validator.

Parses a raw JSON document into a `StateTemplate`:
the document's shape (every section, the name law, no key outside the platform set) is the
contract's `StateTemplateDocument`; this module adds the
rules that span sections or need jq — parameter markers against declared parameters, the
fragment as an object schema, each parameter and declarations schema as a schema whose
references resolve inside it, regime and program paths inside the fragment, program names and
params as jq identifiers, and every inline jq body compiling. A consumer keeps its own documents
beside the template under its own kind (validated through its registered attach validator).

## DECLARATIONS\_CHECK\_VARIABLES

`tai42_skeleton.states.templates.validate.DECLARATIONS_CHECK_VARIABLES`

```python theme={null}
DECLARATIONS_CHECK_VARIABLES: tuple[str, ...] = ('parameters',)
```

## RECONCILE\_JQ\_VARIABLES

`tai42_skeleton.states.templates.validate.RECONCILE_JQ_VARIABLES`

```python theme={null}
RECONCILE_JQ_VARIABLES: dict[str, tuple[str, ...]] = {'orphans': ('previous', 'new'), 'close': ('id', 'resolution'), 'resolutions': ()}
```

## validate\_template

`tai42_skeleton.states.templates.validate.validate_template`

```python theme={null}
validate_template(doc: Any) -> StateTemplate
```

Parse and validate a raw platform state-template document into a `StateTemplate`.

The document must carry `kind == "state-template"` and a dict fragment `schema` (a by-id
fragment is resolved by the caller first) and parse as a
`StateTemplateDocument`; then a no-default parameter
must appear as a marker and every marker names a declared parameter, each parameter and
declarations schema is a valid schema whose references resolve inside it, the defaults-substituted
fragment passes `_validate_schema`, regime and update-program paths lie inside the fragment
(`"*"` only over `items`/`additionalProperties`), program names and params are jq
identifiers, and every inline jq body compiles (a by-id body is rendered and compiled at the
save door). Raises `TemplateValidationError` on the first
violation.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `doc` | `Any` | — | — |


# Settings reference
Source: https://docs.tai42.ai/reference/settings

Every environment variable the tai server reads, grouped by settings group.

> [!NOTE]
>
> Generated from `tai config settings-schema` — do not edit by hand; regenerate
> with `scripts/generate-settings-reference.py`.

Every registered settings group and the environment variables it reads — the core server groups, every first-party plugin's groups, and the per-named-database Postgres group — 606 entries across 100 groups (590 variables and 16 nested-group references). A deployment reads only the groups its manifest loads; a plugin group appears here whether or not a given deployment loads it. Each variable row lists the variable, its type, its default, the `TAI_DEFAULT_*` variable it falls back to when set (a `—` for every field that is not a shared connection identity), whether it is required, its reload class (how a live [settings-profile](/concepts/config-and-secrets#settings-profiles) apply treats a change to it — `hot` re-reads in place, `recycle` rebuilds the pooled resource behind it, `excluded` needs a full restart), and a description where one exists; each nested-group reference row carries no variable of its own and links to that sub-group's section instead. Values shown are code-level defaults; a running server resolves each variable from the environment, then any stored override, then this default.

## AccessControlRedisSettings

Module `tai42_skeleton.access_control.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `ACCESS_CONTROL_SOCKET_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_SOCKET_CONNECT_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_RETRY_ON_TIMEOUT` | `boolean` | `true` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `ACCESS_CONTROL_REDIS_MAX_CONNECTIONS` | `integer` | `10` | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `ACCESS_CONTROL_DECODE_RESPONSES` | `boolean` | `true` | — | Optional | `hot` | — |

## AccessControlSettings

Module `tai42_skeleton.access_control.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `ACCESS_CONTROL_ENABLE` | `boolean` | `true` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_AUTH_PROVIDERS` | `array` | — | — | Optional | `hot` | — |
| `ACCESS_CONTROL_ADMIN` | `string` | — | — | Optional | `hot` | — |
| — | `object` | — | — | Optional | — | Grouped settings — see [AccessControlRedisSettings](#accesscontrolredissettings). |
| `ACCESS_CONTROL_CACHE_SIZE` | `integer` | `5000` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_CACHE_TTL_SECONDS` | `integer` | `60` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_CONTEXT_PREFIX` | `string` | `"ac:context:"` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_SETUP_TOKEN_KEY` | `string` | `"ac:setup:token"` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_SETUP_LOCK_KEY` | `string` | `"ac:setup:lock"` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_SETUP_LOCK_TTL_SECONDS` | `integer` | `10` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_SETUP_THROTTLE_FAIL_PREFIX` | `string` | `"ac:setup:fail:"` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_SETUP_THROTTLE_LOCK_PREFIX` | `string` | `"ac:setup:throttle:"` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_SETUP_THROTTLE_THRESHOLD` | `integer` | `5` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_SETUP_THROTTLE_CAP_SECONDS` | `integer` | `900` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_CLAIM_PREFIX` | `string` | `"ac:claim:"` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_CLAIM_LINK_TTL_SECONDS` | `integer` | `600` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_CLAIM_LINK_MAX_TTL_SECONDS` | `integer` | `3600` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_POLICY_VERSION_KEY` | `string` | `"ac:policy_version"` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_PUBLIC_RESOURCE_ID` | `string` | `"public"` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_RESERVED_PUBLIC_PIN_PREFIXES` | `array` | `["/api/auth"]` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_ALWAYS_PUBLIC_PATH_PREFIXES` | `array` | `[]` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_SPA_SHELL_PUBLIC` | `boolean` | `true` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_RESERVED_OPERATIONAL_SUPPLEMENT` | `array` | `["/openapi.json"]` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_ACKNOWLEDGED_PUBLIC_ROUTES` | `array` | `["/health", "/ready", "/universal_webhook/{topic}", "/trigger/{token}", "/oauth/client-metadata.json", "/.well-known/oauth-protected-resource/{endpoint_path:path}", "/{spa_path:path}"]` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_ALWAYS_PUBLIC_ROUTE_PATTERNS` | `array` | `[]` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_PUBLIC_BASE_URL` | `string` | — | — | Optional | `hot` | — |
| `ACCESS_CONTROL_PATH_PATTERNS` | `object` | `{}` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_COMPILED_PATTERNS` | `array` | `[]` | — | Optional | `hot` | — |
| `ACCESS_CONTROL_COMPILED_ALWAYS_PUBLIC_ROUTE_PATTERNS` | `array` | `[]` | — | Optional | `hot` | — |

## AccountsRedisConnectionSettings

Module `tai42_accounts_postgres.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_ACCOUNTS_SOCKET_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `TAI_ACCOUNTS_SOCKET_CONNECT_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `TAI_ACCOUNTS_RETRY_ON_TIMEOUT` | `boolean` | `true` | — | Optional | `hot` | — |
| `TAI_ACCOUNTS_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `TAI_ACCOUNTS_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `TAI_ACCOUNTS_REDIS_MAX_CONNECTIONS` | `integer` | `10` | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `TAI_ACCOUNTS_DECODE_RESPONSES` | `boolean` | `true` | — | Optional | `hot` | — |

## AccountsSettings

Module `tai42_accounts_postgres.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| — | `object` | — | — | Optional | — | Grouped settings — see [AccountsRedisConnectionSettings](#accountsredisconnectionsettings). |
| `TAI_ACCOUNTS_SESSION_IDLE_SECONDS` | `integer` | `86400` | — | Optional | `hot` | — |
| `TAI_ACCOUNTS_SESSION_ABSOLUTE_SECONDS` | `integer` | `2592000` | — | Optional | `hot` | — |
| `TAI_ACCOUNTS_INVITE_TTL_SECONDS` | `integer` | `259200` | — | Optional | `hot` | — |
| `TAI_ACCOUNTS_LOGIN_BACKOFF_THRESHOLD` | `integer` | `5` | — | Optional | `hot` | — |
| `TAI_ACCOUNTS_LOGIN_BACKOFF_CAP_SECONDS` | `integer` | `900` | — | Optional | `hot` | — |
| `TAI_ACCOUNTS_LOGIN_IP_MAX_ATTEMPTS` | `integer` | `30` | — | Optional | `hot` | — |
| `TAI_ACCOUNTS_LOGIN_IP_WINDOW_SECONDS` | `integer` | `900` | — | Optional | `hot` | — |
| `TAI_ACCOUNTS_LOGIN_HASH_CONCURRENCY` | `integer` | computed at startup | — | Optional | `hot` | — |
| `TAI_ACCOUNTS_LOGIN_HASH_WAIT_SECONDS` | `number` | `2.0` | — | Optional | `hot` | — |
| `TAI_ACCOUNTS_REDIS_KEY_PREFIX` | `string` | — | — | Optional | `hot` | — |

## AgentsLimitsSettings

Module `tai42_agents.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_AGENTS_MAX_VOTERS` | `integer` | `16` | — | Optional | `hot` | — |
| `TAI_AGENTS_VOTER_CONCURRENCY` | `integer` | `8` | — | Optional | `hot` | — |
| `TAI_AGENTS_EMBEDDING_DIMS_CACHE_SIZE` | `integer` | `64` | — | Optional | `hot` | — |
| `TAI_AGENTS_SYSTEM_PROMPT_CACHE_DEFAULT` | `boolean` | `true` | — | Optional | `hot` | — |
| `TAI_AGENTS_CHAINED_PARK_HORIZON_CAP_HOURS` | `integer` | `168` | — | Optional | `hot` | — |
| `TAI_AGENTS_DEFAULT_RECURSION_LIMIT` | `integer` | `50` | — | Optional | `hot` | — |
| `TAI_AGENTS_STRUCTURED_OUTPUT_REPROMPT_CAP` | `integer` | `3` | — | Optional | `hot` | — |
| `TAI_AGENTS_GRAPH_CACHE_SIZE` | `integer` | `64` | — | Optional | `hot` | — |

## AgentsParkRedisSettings

Module `tai42_agents.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_AGENTS_SOCKET_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `TAI_AGENTS_SOCKET_CONNECT_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `TAI_AGENTS_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `TAI_AGENTS_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `TAI_AGENTS_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `TAI_AGENTS_REDIS_MAX_CONNECTIONS` | `integer` | `10` | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `TAI_AGENTS_DECODE_RESPONSES` | `boolean` | `true` | — | Optional | `hot` | — |

## AppArgsSettings

Module `tai42_skeleton.settings.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `APP_ARGS_TRANSPORT` | `string` | `"http"` | — | Optional | `excluded` | — |
| `APP_ARGS_HOST` | `string` | `"127.0.0.1"` | — | Optional | `excluded` | — |
| `APP_ARGS_PORT` | `integer` | `8000` | — | Optional | `excluded` | — |
| `APP_ARGS_UDS` | `string` | — | — | Optional | `excluded` | — |
| `APP_ARGS_TIMEOUT_GRACEFUL_SHUTDOWN` | `integer` | `10` | — | Optional | `recycle` | — |

## ArqRedisSettings

Module `tai42_backend_arq.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `ARQ_SOCKET_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `ARQ_SOCKET_CONNECT_TIMEOUT` | `number` | `1` | — | Optional | `hot` | — |
| `ARQ_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `ARQ_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `ARQ_REDIS_URL` | `string` | `"redis://localhost:6379/0"` | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `ARQ_REDIS_MAX_CONNECTIONS` | `integer` | — | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |

## ArqSettings

Module `tai42_backend_arq.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `ARQ_MANIFEST_KEY` | `string` | `"MANIFEST_KEY"` | — | Optional | `recycle` | — |
| `ARQ_TASK_TIMEOUT` | `integer` | `300` | — | Optional | `recycle` | The dispatch's job budget in seconds: the longest a dispatched job may run on the worker, and how long a synchronous dispatch waits for its result. Worker-side limits are bound when the worker starts, so a change converges through a process recycle. |
| `ARQ_TOOL_NAME_ARG` | `string` | `"backend_tool_name"` | — | Optional | `recycle` | — |
| — | `object` | — | — | Optional | — | Grouped settings — see [ArqRedisSettings](#arqredissettings). |
| `ARQ_QUEUE_NAME` | `string` | `"arq:queue"` | — | Optional | `hot` | — |
| `ARQ_CALLBACK_TIMEOUT` | `integer` | `5` | — | Optional | `hot` | — |
| `ARQ_JOB_COMPLETION_WAIT` | `integer` | `300` | — | Optional | `hot` | — |

## AuditLogSettings

Module `tai42_skeleton.settings.audit_log`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_AUDIT_LOG_ENABLE` | `boolean` | `true` | — | Optional | `hot` | — |

## BatchSettings

Module `tai42_toolbox._internal.extensions.batch_executor`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `BATCH_DEFAULT_MAX_CONCURRENT` | `integer` | `5` | — | Optional | `hot` | — |
| `BATCH_MAX_BATCH_SIZE` | `integer` | `100` | — | Optional | `hot` | — |

## BodyLimitSettings

Module `tai42_skeleton.settings.body_limit`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_BODY_LIMIT_MAX_BODY_BYTES` | `integer` | `10485760` | — | Optional | `hot` | — |

## BusRedisSettings

Module `tai42_skeleton.app.bus_settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_BUS_SOCKET_TIMEOUT` | `number` | — | — | Optional | `recycle` | — |
| `TAI_BUS_SOCKET_CONNECT_TIMEOUT` | `number` | — | — | Optional | `recycle` | — |
| `TAI_BUS_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `recycle` | — |
| `TAI_BUS_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `recycle` | — |
| `TAI_BUS_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `recycle` | — |
| `TAI_BUS_REDIS_MAX_CONNECTIONS` | `integer` | — | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `recycle` | — |
| `TAI_BUS_DECODE_RESPONSES` | `boolean` | `true` | — | Optional | `recycle` | — |

## BusSettings

Module `tai42_skeleton.app.bus_settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| — | `object` | — | — | Optional | — | Grouped settings — see [BusRedisSettings](#busredissettings). |
| `TAI_BUS_NAMESPACE` | `string` | `"tai"` | — | Optional | `recycle` | — |
| `TAI_BUS_ACK_TIMEOUT` | `number` | `2.0` | — | Optional | `recycle` | — |
| `TAI_BUS_APPLY_TIMEOUT` | `number` | `90.0` | — | Optional | `recycle` | — |
| `TAI_BUS_HEARTBEAT_TTL` | `number` | `15.0` | — | Optional | `recycle` | — |

## CacheSettings

Module `tai42_toolbox._internal.extensions.cache_store`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CACHE_MAX_ENTRIES` | `integer` | `1024` | — | Optional | `hot` | — |

## CeleryBrokerRedisOptions

Module `tai42_backend_celery.core.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CELERY_BROKER_SOCKET_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `CELERY_BROKER_SOCKET_CONNECT_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `CELERY_BROKER_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `CELERY_BROKER_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |

## CeleryRedbeatRedisSettings

Module `tai42_backend_celery.core.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CELERY_REDBEAT_SOCKET_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `CELERY_REDBEAT_SOCKET_CONNECT_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `CELERY_REDBEAT_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `CELERY_REDBEAT_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `CELERY_REDBEAT_REDIS_URL` | `string` | `"redis://localhost:6379/0"` | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `CELERY_REDBEAT_REDIS_MAX_CONNECTIONS` | `integer` | — | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |

## CeleryResultBackendRedisOptions

Module `tai42_backend_celery.core.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CELERY_RESULT_BACKEND_SOCKET_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `CELERY_RESULT_BACKEND_SOCKET_CONNECT_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `CELERY_RESULT_BACKEND_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `CELERY_RESULT_BACKEND_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |

## CelerySettings

Module `tai42_backend_celery.core.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CELERY_MANIFEST_KEY` | `string` | `"MANIFEST_KEY"` | — | Optional | `recycle` | — |
| `CELERY_TASK_TIMEOUT` | `integer` | `300` | — | Optional | `recycle` | The dispatch's job budget in seconds: the longest a dispatched job may run on the worker, and how long a synchronous dispatch waits for its result. Worker-side limits are bound when the worker starts, so a change converges through a process recycle. |
| `CELERY_TOOL_NAME_ARG` | `string` | `"backend_tool_name"` | — | Optional | `recycle` | — |
| `CELERY_BROKER_URL` | `string` | `"amqp://localhost:5672//"` | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `CELERY_RESULT_BACKEND` | `string` | `"redis://localhost:6379/0"` | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| — | `object` | — | — | Optional | — | Grouped settings — see [CeleryBrokerRedisOptions](#celerybrokerredisoptions). |
| — | `object` | — | — | Optional | — | Grouped settings — see [CeleryResultBackendRedisOptions](#celeryresultbackendredisoptions). |
| — | `object` | — | — | Optional | — | Grouped settings — see [CeleryRedbeatRedisSettings](#celeryredbeatredissettings). |
| `CELERY_REDBEAT_KEY_PREFIX` | `string` | `"redbeat:"` | — | Optional | `hot` | — |
| `CELERY_BEAT_MAX_LOOP_INTERVAL` | `integer` | `60` | — | Optional | `hot` | — |
| `CELERY_WORKER_CONCURRENCY` | `integer` | `1` | — | Optional | `hot` | — |

## ChannelsSettings

Module `tai42_skeleton.channels.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CHANNELS_NOTIFICATIONS_FEED_MAX` | `integer` | `1000` | — | Optional | `hot` | — |
| `CHANNELS_NOTIFICATIONS_FEED_TTL_SECONDS` | `integer` | `2592000` | — | Optional | `hot` | — |
| `CHANNELS_SEND_RECEIPT_INDEX_TTL_SECONDS` | `integer` | `86400` | — | Optional | `hot` | — |

## ClassifierSettings

Module `tai42_kit.llm.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CLASSIFIER_MODEL` | `string` | `"jev-latest"` | — | Optional | `hot` | — |
| `CLASSIFIER_BASE_URL` | `string` | — | — | Optional | `hot` | — |
| `CLASSIFIER_API_KEY` | `string` | — | — | Optional | `hot` | Secret. |
| `CLASSIFIER_TIMEOUT` | `integer` | — | — | Optional | `hot` | — |

## ClaudeCodeSettings

Module `tai42_agents.claude_code.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_AGENTS_CLAUDE_API_KEY` | `string` | — | — | Optional | `hot` | Secret. |
| `TAI_AGENTS_CLAUDE_OAUTH_TOKEN` | `string` | — | — | Optional | `hot` | Secret. |
| `TAI_AGENTS_CLAUDE_SESSION_IMAGE` | `string` | — | — | Required | `hot` | — |
| `TAI_AGENTS_CLAUDE_CREDS` | `array` | `[]` | — | Optional | `hot` | — |
| `TAI_AGENTS_CLAUDE_HOOK_SETTINGS` | `object` | — | — | Optional | `hot` | — |
| `TAI_AGENTS_CLAUDE_MODEL` | `string` | — | — | Optional | `hot` | — |
| `TAI_AGENTS_CLAUDE_MAX_TURNS` | `integer` | `100` | — | Optional | `hot` | — |
| `TAI_AGENTS_CLAUDE_MAX_BUDGET_USD` | `number` | — | — | Optional | `hot` | — |
| `TAI_AGENTS_CLAUDE_RUN_TIMEOUT_SECONDS` | `integer` | `3600` | — | Optional | `hot` | — |
| `TAI_AGENTS_CLAUDE_SESSION_TTL_SECONDS` | `integer` | `86400` | — | Optional | `hot` | — |
| `TAI_AGENTS_CLAUDE_NETWORK` | `string` | — | — | Optional | `hot` | — |
| `TAI_AGENTS_CLAUDE_CRASH_RESUME` | `boolean` | `false` | — | Optional | `recycle` | — |

## ClientTrustSettings

Module `tai42_kit.utils.client_address`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_RATE_LIMIT_TRUSTED_PROXIES` | `array` | `[]` | — | Optional | `hot` | — |
| `TAI_RATE_LIMIT_TRUSTED_HOPS` | `integer` | `0` | — | Optional | `hot` | — |

## ConfigModeSettings

Module `tai42_skeleton.config.config_mode`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_CONFIG_MODE` | `string` | `"file"` | — | Optional | `excluded` | — |
| `TAI_CONFIG_DIR_PATH` | `string` | — | — | Optional | `excluded` | — |

## ConnectorAdapterSettings

Module `tai42_skeleton.connectors.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CONNECTORS_META_TOKEN_KEY` | `string` | `"tai_hub.access_token"` | — | Optional | `hot` | — |
| `CONNECTORS_ERROR_PREFIX` | `string` | `"tai-hub-err:"` | — | Optional | `hot` | — |

## ConnectorCryptoSecrets

Module `tai42_skeleton.connectors.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CONNECTORS_KEK` | `string` | — | — | Optional | `hot` | Secret. Key material — refused in a settings profile; rotate through its own path. |
| `CONNECTORS_KEK_PREVIOUS` | `string` | — | — | Optional | `hot` | Secret. Key material — refused in a settings profile; rotate through its own path. |
| `CONNECTORS_STATE_HMAC_KEY` | `string` | — | — | Optional | `hot` | Secret. Key material — refused in a settings profile; rotate through its own path. |

## ConnectorEngineConfig

Module `tai42_skeleton.connectors.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CONNECTORS_MAX_SESSION_TTL` | `string` | — | — | Optional | `hot` | — |
| `CONNECTORS_REDIRECT_URI_ALLOWLIST` | `string` | `""` | — | Optional | `hot` | — |
| `CONNECTORS_OAUTH_BRIDGE_URL` | `string` | — | — | Optional | `hot` | — |
| `CONNECTORS_CLIENT_NAME` | `string` | `"Tai"` | — | Optional | `hot` | — |
| `CONNECTORS_CLIENT_ID_DOCUMENT` | `boolean` | `true` | — | Optional | `hot` | — |

## ConnectorStoreRedisSettings

Module `tai42_skeleton.connectors.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CONNECTOR_STORE_SOCKET_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `CONNECTOR_STORE_SOCKET_CONNECT_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `CONNECTOR_STORE_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `CONNECTOR_STORE_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `CONNECTOR_STORE_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `CONNECTOR_STORE_REDIS_MAX_CONNECTIONS` | `integer` | `10` | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `CONNECTOR_STORE_DECODE_RESPONSES` | `boolean` | `false` | — | Optional | `hot` | — |

## ConnectorStoreSettings

Module `tai42_skeleton.connectors.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| — | `object` | — | — | Optional | — | Grouped settings — see [ConnectorStoreRedisSettings](#connectorstoreredissettings). |
| `CONNECTOR_STORE_KEY_PREFIX` | `string` | `"connectors:"` | — | Optional | `hot` | — |

## ContextEditingSettings

Module `tai42_kit.llm.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CONTEXT_EDITING_TRIGGER_TOKENS` | `integer` | `100000` | — | Optional | `hot` | — |
| `CONTEXT_EDITING_KEEP_TOOL_RESULTS` | `integer` | `3` | — | Optional | `hot` | — |
| `CONTEXT_EDITING_CLEAR_AT_LEAST` | `integer` | `0` | — | Optional | `hot` | — |
| `CONTEXT_EDITING_CLEAR_TOOL_INPUTS` | `boolean` | `false` | — | Optional | `hot` | — |
| `CONTEXT_EDITING_EXCLUDE_TOOLS` | `array` | `[]` | — | Optional | `hot` | — |

## ContextOverflowSettings

Module `tai42_kit.llm.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CONTEXT_OVERFLOW_METHODS` | `array` | `["trimming"]` | — | Optional | `hot` | — |

## ConversationsRedisSettings

Module `tai42_skeleton.conversations.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CONVERSATIONS_SOCKET_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `CONVERSATIONS_SOCKET_CONNECT_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `CONVERSATIONS_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `CONVERSATIONS_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `CONVERSATIONS_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `CONVERSATIONS_REDIS_MAX_CONNECTIONS` | `integer` | — | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `CONVERSATIONS_DECODE_RESPONSES` | `boolean` | `true` | — | Optional | `hot` | — |

## ConversationsSettings

Module `tai42_skeleton.conversations.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| — | `object` | — | — | Optional | — | Grouped settings — see [ConversationsRedisSettings](#conversationsredissettings). |
| `CONVERSATIONS_PREFIX` | `string` | `"conversations"` | — | Optional | `hot` | — |
| `CONVERSATIONS_MAX_CONCURRENT_TURNS` | `integer` | `10` | — | Optional | `hot` | — |
| `CONVERSATIONS_THREAD_QUEUE_DEPTH` | `integer` | `20` | — | Optional | `hot` | — |
| `CONVERSATIONS_PER_ADDRESS_TURNS_PER_HOUR` | `integer` | `20` | — | Optional | `hot` | — |
| `CONVERSATIONS_ADDRESS_BUCKET_MAX_ENTRIES` | `integer` | `50000` | — | Optional | `hot` | — |
| `CONVERSATIONS_SYNC_WAIT_MAX_SECONDS` | `integer` | `120` | — | Optional | `hot` | — |
| `CONVERSATIONS_INTAKE_CLAIM_LEASE_SECONDS` | `integer` | `120` | — | Optional | `hot` | — |
| `CONVERSATIONS_INTAKE_CLAIM_REFRESH_SECONDS` | `integer` | `30` | — | Optional | `hot` | — |
| `CONVERSATIONS_THREAD_LEASE_SECONDS` | `integer` | `120` | — | Optional | `hot` | — |
| `CONVERSATIONS_THREAD_LEASE_REFRESH_SECONDS` | `integer` | `30` | — | Optional | `hot` | — |
| `CONVERSATIONS_OVERLAP_CANCEL_POLL_SECONDS` | `number` | `0.5` | — | Optional | `hot` | — |
| `CONVERSATIONS_SYNC_DOOR_WAIT_SECONDS` | `number` | `30` | — | Optional | `hot` | — |
| `CONVERSATIONS_WORKING_SIGNAL_MAX_SECONDS` | `number` | `180.0` | — | Optional | `hot` | — |
| `CONVERSATIONS_WORKING_SIGNAL_REFRESH_MARGIN_SECONDS` | `number` | `5.0` | — | Optional | `hot` | — |
| `CONVERSATIONS_DELIVERY_MAX_ATTEMPTS` | `integer` | `8` | — | Optional | `hot` | — |
| `CONVERSATIONS_DELIVERY_BACKOFF_BASE_SECONDS` | `number` | `60` | — | Optional | `hot` | — |
| `CONVERSATIONS_DELIVERY_BACKOFF_MAX_SECONDS` | `number` | `900` | — | Optional | `hot` | — |
| `CONVERSATIONS_DELIVERY_CLAIM_LEASE_SECONDS` | `integer` | `120` | — | Optional | `hot` | — |
| `CONVERSATIONS_DELIVERY_SEND_TIMEOUT_SECONDS` | `number` | `60` | — | Optional | `hot` | — |
| `CONVERSATIONS_DELIVERY_CALLBACK_TIMEOUT_SECONDS` | `number` | `15` | — | Optional | `hot` | — |
| `CONVERSATIONS_DELIVERY_SWEEP_INTERVAL_SECONDS` | `integer` | `60` | — | Optional | `hot` | — |
| `CONVERSATIONS_DELIVERY_GRACE_SECONDS` | `integer` | `3600` | — | Optional | `hot` | — |
| `CONVERSATIONS_MAX_MESSAGE_CHARS` | `object` | `{}` | — | Optional | `hot` | — |
| `CONVERSATIONS_MAX_OUTBOUND_CHUNKS` | `integer` | `10` | — | Optional | `hot` | — |
| `CONVERSATIONS_INBOUND_DEDUPE_TTL_SECONDS` | `integer` | `172800` | — | Optional | `hot` | — |
| `CONVERSATIONS_ANSWER_RETENTION_TTL_SECONDS` | `integer` | `2592000` | — | Optional | `hot` | — |
| `CONVERSATIONS_PAIR_CODE_TTL_SECONDS` | `integer` | `900` | — | Optional | `hot` | — |
| `CONVERSATIONS_OWED_GREETING_TTL_SECONDS` | `integer` | `86400` | — | Optional | `hot` | — |
| `CONVERSATIONS_REDEEM_BACKOFF_THRESHOLD` | `integer` | `5` | — | Optional | `hot` | — |
| `CONVERSATIONS_REDEEM_BACKOFF_CAP_SECONDS` | `integer` | `900` | — | Optional | `hot` | — |

## CoreSettings

Module `tai42_skeleton.settings.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_MANIFEST_PATH` | `string` | — | — | Optional | `excluded` | — |
| `TAI_MCP_BACKEND` | `string` | — | — | Optional | `recycle` | — |
| `TAI_MCP_TEMPLATE` | `string` | — | — | Optional | `recycle` | — |
| `TAI_MCP_SANDBOX` | `string` | — | — | Optional | `recycle` | — |
| `TAI_MCP_SANDBOX_EGRESS` | `string` | `"egress"` | — | Optional | `recycle` | — |
| `TAI_MCP_SANDBOX_ISOLATION` | `string` | `"container"` | — | Optional | `recycle` | — |
| `TAI_MCP_SANDBOX_SCRUB_TRANSCRIPT` | `boolean` | `false` | — | Optional | `recycle` | — |
| `TAI_MCP_SANDBOX_DURABLE` | `boolean` | `true` | — | Optional | `recycle` | — |
| `TAI_MCP_MCP_PROBE_TIMEOUT` | `number` | `15.0` | — | Optional | `hot` | — |
| `TAI_MCP_MCP_RELOAD_PROBE_TIMEOUT` | `number` | `3.0` | — | Optional | `hot` | — |
| `TAI_MCP_MCP_REPROBE_INITIAL_SECONDS` | `number` | `30.0` | — | Optional | `hot` | — |
| `TAI_MCP_MCP_REPROBE_MAX_SECONDS` | `number` | `600.0` | — | Optional | `hot` | — |

## DatabaseConnection

Module `tai42_kit.clients.settings`.

One connection block per named database, read under the `TAI_DATABASE_<NAME>_` prefix (`<NAME>` is a placeholder for the database name). `default` is the database every core Postgres store binds to unless a component names another.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_DATABASE_<NAME>_PG_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `TAI_DATABASE_<NAME>_PG_HOST` | `string` | — | — | Optional | `hot` | — |
| `TAI_DATABASE_<NAME>_PG_PORT` | `integer` | `5432` | — | Optional | `hot` | — |
| `TAI_DATABASE_<NAME>_PG_DB` | `string` | `"postgres"` | — | Optional | `hot` | — |
| `TAI_DATABASE_<NAME>_PG_USER` | `string` | `"postgres"` | — | Optional | `hot` | — |
| `TAI_DATABASE_<NAME>_PG_PASSWORD` | `string` | — | — | Optional | `hot` | Secret. |
| `TAI_DATABASE_<NAME>_PG_MIN_CONNECTIONS` | `integer` | `2` | — | Optional | `hot` | — |
| `TAI_DATABASE_<NAME>_PG_MAX_CONNECTIONS` | `integer` | `10` | — | Optional | `hot` | — |
| `TAI_DATABASE_<NAME>_PG_CONNECT_TIMEOUT` | `integer` | `10` | — | Optional | `hot` | — |
| `TAI_DATABASE_<NAME>_PG_STATEMENT_TIMEOUT_SECONDS` | `number` | `60` | — | Optional | `hot` | — |

## DockerSandboxSettings

Module `tai42_sandbox_docker.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `SANDBOX_DOCKER_REAP_INTERVAL_SECONDS` | `integer` | `300` | — | Optional | `hot` | — |
| `SANDBOX_DOCKER_EXEC_DEFAULT_TIMEOUT_SECONDS` | `integer` | `300` | — | Optional | `hot` | — |
| `SANDBOX_DOCKER_HOST` | `string` | — | — | Required | `hot` | — |
| `SANDBOX_DOCKER_TLS_VERIFY` | `boolean` | `true` | — | Optional | `hot` | — |
| `SANDBOX_DOCKER_TLS_CERT_PATH` | `string` | `"/certs/client/cert.pem"` | — | Optional | `hot` | — |
| `SANDBOX_DOCKER_TLS_KEY_PATH` | `string` | `"/certs/client/key.pem"` | — | Optional | `hot` | — |
| `SANDBOX_DOCKER_TLS_CA_PATH` | `string` | `"/certs/client/ca.pem"` | — | Optional | `hot` | — |
| `SANDBOX_DOCKER_DEFAULT_CPU` | `number` | — | — | Optional | `hot` | — |
| `SANDBOX_DOCKER_DEFAULT_MEMORY_MB` | `integer` | — | — | Optional | `hot` | — |
| `SANDBOX_DOCKER_PULL_POLICY` | `string` | `"missing"` | — | Optional | `hot` | — |
| `SANDBOX_DOCKER_READINESS_PROBE_ENABLED` | `boolean` | `false` | — | Optional | `hot` | — |
| `SANDBOX_DOCKER_READINESS_PROBE_IMAGE` | `string` | `"busybox:latest"` | — | Optional | `hot` | — |
| `SANDBOX_DOCKER_READINESS_PROBE_TIMEOUT_SECONDS` | `number` | `30.0` | — | Optional | `hot` | — |

## EmbeddingSettings

Module `tai42_kit.llm.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `EMBEDDING_MODEL` | `string` | `"text-embedding-3-small"` | — | Optional | `hot` | — |
| `EMBEDDING_BASE_URL` | `string` | — | — | Optional | `hot` | — |
| `EMBEDDING_API_KEY` | `string` | — | — | Optional | `hot` | Secret. |
| `EMBEDDING_API_VERSION` | `string` | — | — | Optional | `hot` | — |
| `EMBEDDING_TIMEOUT` | `integer` | — | — | Optional | `hot` | — |
| `EMBEDDING_USER_AGENT` | `string` | — | — | Optional | `hot` | — |
| `EMBEDDING_TASK` | `string` | — | — | Optional | `hot` | — |
| `EMBEDDING_MODEL_KWARGS` | `object` | — | — | Optional | `hot` | — |

## EnvSecretMarksSettings

Module `tai42_skeleton.settings.env_secret_marks`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_ENV_SECRET_KEYS` | `array` | `[]` | — | Optional | `hot` | — |

## FileLoadingSettings

Module `tai42_skeleton.template.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `FILE_LOADING_MAX_BYTES` | `integer` | `26214400` | — | Optional | `hot` | — |

## GithubStorageSettings

Module `tai42_storage_github.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `STORAGE_GITHUB_USERNAME` | `string` | — | — | Optional | `hot` | — |
| `STORAGE_GITHUB_REPO` | `string` | — | — | Optional | `hot` | — |
| `STORAGE_GITHUB_BRANCH` | `string` | `"main"` | — | Optional | `hot` | — |
| `STORAGE_GITHUB_TOKEN` | `string` | — | — | Optional | `hot` | Secret. |
| `STORAGE_GITHUB_RAW_BASE_URL` | `string` | `"https://raw.githubusercontent.com/{username}/{repo}/refs/heads/{branch}"` | — | Optional | `hot` | — |
| `STORAGE_GITHUB_CONTENTS_API_URL` | `string` | `"https://api.github.com/repos/{username}/{repo}/contents"` | — | Optional | `hot` | — |
| `STORAGE_GITHUB_TREES_API_URL` | `string` | `"https://api.github.com/repos/{username}/{repo}/git/trees/{branch}"` | — | Optional | `hot` | — |
| `STORAGE_GITHUB_TIMEOUT_TOTAL` | `number` | `15.0` | — | Optional | `hot` | — |
| `STORAGE_GITHUB_MAX_CONNECTIONS` | `integer` | `200` | — | Optional | `hot` | — |
| `STORAGE_GITHUB_MAX_KEEPALIVE_CONNECTIONS` | `integer` | `50` | — | Optional | `hot` | — |
| `STORAGE_GITHUB_KEEPALIVE_EXPIRY` | `number` | `300.0` | — | Optional | `hot` | — |

## GithubToolsSettings

Module `tai42_tools_github._internal.tools.github_client`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TOOLS_GITHUB_TOKEN` | `string` | — | — | Optional | `hot` | Secret. |
| `TOOLS_GITHUB_API_BASE` | `string` | `"https://api.github.com"` | — | Optional | `hot` | — |
| `TOOLS_GITHUB_REQUEST_TIMEOUT_SECONDS` | `number` | `20` | — | Optional | `hot` | — |

## HooksRedisSettings

Module `tai42_skeleton.hooks.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `HOOKS_SOCKET_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `HOOKS_SOCKET_CONNECT_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `HOOKS_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `HOOKS_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `HOOKS_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `HOOKS_REDIS_MAX_CONNECTIONS` | `integer` | — | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `HOOKS_DECODE_RESPONSES` | `boolean` | `true` | — | Optional | `hot` | — |

## HooksSettings

Module `tai42_skeleton.hooks.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| — | `object` | — | — | Optional | — | Grouped settings — see [HooksRedisSettings](#hooksredissettings). |
| `HOOKS_MAX_WORKERS` | `integer` | `10` | — | Optional | `hot` | — |
| `HOOKS_PREFIX` | `string` | `"hooks"` | — | Optional | `hot` | — |
| `HOOKS_RUN_MAX_ATTEMPTS` | `integer` | `5` | — | Optional | `hot` | — |
| `HOOKS_RUN_RETRY_BASE_SECONDS` | `number` | `10.0` | — | Optional | `hot` | — |
| `HOOKS_RUN_RETRY_CAP_SECONDS` | `number` | `600.0` | — | Optional | `hot` | — |
| `HOOKS_RUN_LEASE_SECONDS` | `number` | `60.0` | — | Optional | `hot` | — |
| `HOOKS_RUN_SWEEP_SECONDS` | `number` | `5.0` | — | Optional | `hot` | — |
| `HOOKS_RUN_SHUTDOWN_GRACE_SECONDS` | `number` | `20.0` | — | Optional | `hot` | — |

## HostedUiSettings

Module `tai42_skeleton.plugins.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `HOSTED_UI_LOGIN_PATH` | `string` | `"/login"` | — | Optional | `hot` | — |
| `HOSTED_UI_CLAIM_FRAGMENT_KEY` | `string` | `"claim"` | — | Optional | `hot` | — |
| `HOSTED_UI_INVITE_QUERY_KEY` | `string` | `"invite"` | — | Optional | `hot` | — |
| `HOSTED_UI_OAUTH_CALLBACK_PATH` | `string` | `"/oauth-bridge.html"` | — | Optional | `hot` | — |
| `HOSTED_UI_CONNECTORS_PATH` | `string` | `"/connectors"` | — | Optional | `hot` | — |

## InteractionsRedisSettings

Module `tai42_skeleton.interactions.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `INTERACTIONS_SOCKET_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `INTERACTIONS_SOCKET_CONNECT_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `INTERACTIONS_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `INTERACTIONS_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `INTERACTIONS_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `INTERACTIONS_REDIS_MAX_CONNECTIONS` | `integer` | `10` | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `INTERACTIONS_DECODE_RESPONSES` | `boolean` | `true` | — | Optional | `hot` | — |

## InteractionsSettings

Module `tai42_skeleton.interactions.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| — | `object` | — | — | Optional | — | Grouped settings — see [InteractionsRedisSettings](#interactionsredissettings). |
| `INTERACTIONS_KEY_PREFIX` | `string` | `"interactions:"` | — | Optional | `hot` | — |
| `INTERACTIONS_ANSWER_TIMEOUT_SECONDS` | `integer` | `3600` | — | Optional | `hot` | — |
| `INTERACTIONS_IDLE_TTL_SECONDS` | `integer` | `86400` | — | Optional | `hot` | — |
| `INTERACTIONS_PUBLIC_BASE_URL` | `string` | — | — | Optional | `hot` | — |
| `INTERACTIONS_CALLBACK_MAX_BODY_BYTES` | `integer` | `65536` | — | Optional | `hot` | — |
| `INTERACTIONS_MAX_CONCURRENT` | `integer` | `1000` | — | Optional | `hot` | — |
| `INTERACTIONS_MAX_CONCURRENT_CALLER` | `integer` | `10000` | — | Optional | `hot` | — |
| `INTERACTIONS_DELIVERY_MAX_ATTEMPTS` | `integer` | `3` | — | Optional | `hot` | — |
| `INTERACTIONS_DELIVERY_RETRY_BACKOFF_SECONDS` | `number` | `1.0` | — | Optional | `hot` | — |
| `INTERACTIONS_BLOCKING_GRACE_SECONDS` | `number` | `5` | — | Optional | `hot` | — |
| `INTERACTIONS_EXPIRY_REAPER_INTERVAL_SECONDS` | `number` | `30` | — | Optional | `hot` | — |
| `INTERACTIONS_REACTION_DEADLINE_SECONDS` | `number` | `10` | — | Optional | `hot` | — |
| `INTERACTIONS_CALLBACK_GONE_TEXT` | `string` | `"Not Found"` | — | Optional | `hot` | — |
| `INTERACTIONS_CALLBACK_FAULT_TEXT` | `string` | `"Internal Server Error"` | — | Optional | `hot` | — |

## JqSettings

Module `tai42_kit.utils.data.jq_util`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `JQ_TIMEOUT_SECONDS` | `number` | `10` | — | Optional | `hot` | — |

## LLMProviderSettings

Module `tai42_kit.llm.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `LLM_PROVIDER_LLM` | `string` | `"openai"` | — | Optional | `hot` | — |
| `LLM_PROVIDER_EMBEDDING` | `string` | `"openai"` | — | Optional | `hot` | — |
| `LLM_PROVIDER_CLASSIFIER` | `string` | `"typesafe"` | — | Optional | `hot` | — |
| `LLM_PROVIDER_CHECKPOINT` | `string` | `"redis"` | — | Optional | `hot` | — |
| `LLM_PROVIDER_CHECKPOINT_CONN_STRING` | `string` | — | — | Optional | `hot` | — |
| `LLM_PROVIDER_CHECKPOINT_RETENTION_WAITING_MINUTES` | `integer` | `10080` | — | Optional | `hot` | — |
| `LLM_PROVIDER_CHECKPOINT_RETENTION_FINISHED_MINUTES` | `integer` | `1440` | — | Optional | `hot` | — |
| `LLM_PROVIDER_CHECKPOINT_INLINE_COMPRESS_BYTES` | `integer` | `65536` | — | Optional | `hot` | — |
| `LLM_PROVIDER_CHECKPOINT_SHARED_VALUES` | `boolean` | — | — | Optional | `hot` | Store large checkpoint sub-values once per thread: unset, on for a store that copies channel values into every checkpoint and off for one that stores a channel once per version; `true`/`false` set it for every store this deployment opens. |
| `LLM_PROVIDER_CHECKPOINT_SHARED_VALUE_BYTES` | `integer` | `65536` | — | Optional | `hot` | Where large values are stored once, a sub-value whose encoding is larger than this many bytes is stored once per thread and referenced. |
| `LLM_PROVIDER_STORE` | `string` | `"redis"` | — | Optional | `hot` | — |
| `LLM_PROVIDER_STORE_CONN_STRING` | `string` | — | — | Optional | `hot` | — |

## LLMSettings

Module `tai42_kit.llm.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `LLM_MODEL` | `string` | `"gpt-4o"` | — | Optional | `hot` | — |
| `LLM_TEMPERATURE` | `number` | — | — | Optional | `hot` | — |
| `LLM_MAX_TOKENS` | `integer` | — | — | Optional | `hot` | — |
| `LLM_TIMEOUT` | `integer` | — | — | Optional | `hot` | — |
| `LLM_BASE_URL` | `string` | — | — | Optional | `hot` | — |
| `LLM_API_KEY` | `string` | — | — | Optional | `hot` | Secret. |
| `LLM_API_VERSION` | `string` | — | — | Optional | `hot` | — |
| `LLM_TOP_P` | `number` | — | — | Optional | `hot` | — |
| `LLM_TOP_K` | `integer` | — | — | Optional | `hot` | — |
| `LLM_N` | `integer` | — | — | Optional | `hot` | — |
| `LLM_REASONING_EFFORT` | `string` | — | — | Optional | `hot` | — |

## LangchainDeepAgentSettings

Module `tai42_agents.langchain_deep_agent.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_AGENTS_LANGCHAIN_DEEP_SESSION_IMAGE` | `string` | `""` | — | Optional | `hot` | — |
| `TAI_AGENTS_LANGCHAIN_DEEP_CREDS` | `array` | `[]` | — | Optional | `hot` | — |
| `TAI_AGENTS_LANGCHAIN_DEEP_SESSION_TTL_SECONDS` | `integer` | `86400` | — | Optional | `hot` | — |
| `TAI_AGENTS_LANGCHAIN_DEEP_NETWORK` | `string` | — | — | Optional | `hot` | — |
| `TAI_AGENTS_LANGCHAIN_DEEP_CPU` | `number` | — | — | Optional | `hot` | — |
| `TAI_AGENTS_LANGCHAIN_DEEP_MEMORY_MB` | `integer` | — | — | Optional | `hot` | — |
| `TAI_AGENTS_LANGCHAIN_DEEP_CRASH_RESUME` | `boolean` | `false` | — | Optional | `recycle` | — |

## LangfuseSettings

Module `tai42_monitoring_langfuse.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `LANGFUSE_PUBLIC_KEY` | `string` | `""` | — | Optional | `hot` | — |
| `LANGFUSE_SECRET_KEY` | `string` | — | — | Optional | `hot` | Secret. |
| `LANGFUSE_HOST` | `string` | `""` | — | Optional | `hot` | — |
| `LANGFUSE_TIMEOUT_SECONDS` | `integer` | `30` | — | Optional | `hot` | — |
| `LANGFUSE_TRACING_ENVIRONMENT` | `string` | `"tai"` | — | Optional | `hot` | — |

## LlmCheckpointConnectionOptions

Module `tai42_kit.llm.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `LLM_PROVIDER_CHECKPOINT_PG_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `LLM_PROVIDER_CHECKPOINT_SOCKET_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `LLM_PROVIDER_CHECKPOINT_SOCKET_CONNECT_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `LLM_PROVIDER_CHECKPOINT_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `LLM_PROVIDER_CHECKPOINT_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |

## LlmStoreConnectionOptions

Module `tai42_kit.llm.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `LLM_PROVIDER_STORE_PG_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `LLM_PROVIDER_STORE_SOCKET_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `LLM_PROVIDER_STORE_SOCKET_CONNECT_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `LLM_PROVIDER_STORE_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `LLM_PROVIDER_STORE_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |

## LocalStorageSettings

Module `tai42_storage_local.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `STORAGE_LOCAL_ROOT_PATH` | `string` | — | — | Optional | `hot` | — |
| `STORAGE_LOCAL_CREATE_DIRS` | `boolean` | `true` | — | Optional | `hot` | — |

## LoggingSettings

Module `tai42_kit.logging.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_LOG_LEVEL` | `string` | `"INFO"` | — | Optional | `hot` | — |

## MCPClientSettings

Module `tai42_kit.clients.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `MCP_CLIENT_CONNECT_TIMEOUT_SECONDS` | `number` | `30` | — | Optional | `hot` | — |
| `MCP_CLIENT_CALL_TIMEOUT_SECONDS` | `number` | `300` | — | Optional | `hot` | — |
| `MCP_CLIENT_KEEPALIVE_EXPIRY_SECONDS` | `number` | `30` | — | Optional | `hot` | — |

## MCPDispatchSettings

Module `tai42_skeleton.settings.mcp_settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_MCP_CALL_TIMEOUT_SECONDS` | `number` | `300` | — | Optional | `hot` | — |
| `TAI_MCP_SCHEMA_MAX_DEPTH` | `integer` | `50` | — | Optional | `hot` | — |

## MarketplaceSettings

Module `tai42_skeleton.marketplace.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `MARKETPLACE_URL` | `string` | `"https://marketplace.tai42.ai"` | — | Optional | `hot` | — |
| `MARKETPLACE_ADVISORIES_POLL` | `boolean` | `true` | — | Optional | `hot` | — |
| `MARKETPLACE_ADVISORIES_INTERVAL_S` | `integer` | `3600` | — | Optional | `hot` | — |
| `MARKETPLACE_REQUEST_TIMEOUT_S` | `number` | `15` | — | Optional | `hot` | — |

## MediaIngestCapSettings

Module `tai42_kit.interactions.media_caps`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `MEDIA_INGEST_MAX_IMAGE_BYTES` | `integer` | `8388608` | — | Optional | `hot` | — |
| `MEDIA_INGEST_MAX_AUDIO_BYTES` | `integer` | `16777216` | — | Optional | `hot` | — |
| `MEDIA_INGEST_MAX_VIDEO_BYTES` | `integer` | `26214400` | — | Optional | `hot` | — |
| `MEDIA_INGEST_MAX_DOCUMENT_BYTES` | `integer` | `26214400` | — | Optional | `hot` | — |

## MediaIngestSettings

Module `tai42_skeleton.settings.media_ingest`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `MEDIA_INGEST_IMAGE_MIME_ALLOWLIST` | `array` | — | — | Optional | `hot` | — |
| `MEDIA_INGEST_AUDIO_MIME_ALLOWLIST` | `array` | — | — | Optional | `hot` | — |
| `MEDIA_INGEST_VIDEO_MIME_ALLOWLIST` | `array` | — | — | Optional | `hot` | — |
| `MEDIA_INGEST_DOCUMENT_MIME_ALLOWLIST` | `array` | — | — | Optional | `hot` | — |
| `MEDIA_INGEST_DOCUMENT_NONE_SNIFF_MIME_ALLOWLIST` | `array` | — | — | Optional | `hot` | — |
| `MEDIA_INGEST_REAPER_INTERVAL_SECONDS` | `integer` | `300` | — | Optional | `hot` | — |
| `MEDIA_INGEST_PENDING_TTL_SECONDS` | `integer` | `900` | — | Optional | `hot` | — |

## MetricsSettings

Module `tai42_skeleton.routers.metrics_settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `BACKEND_METRICS_HOST` | `string` | `"127.0.0.1"` | — | Optional | `excluded` | — |
| `BACKEND_METRICS_PORT` | `integer` | `8012` | — | Optional | `excluded` | — |
| `PROMETHEUS_MULTIPROC_DIR` | `string` | `"/tmp/tai42_prometheus"` | — | Optional | `excluded` | — |

## PluginPrefixSettings

Module `tai42_skeleton.marketplace.prefix`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_PLUGINS_PREFIX` | `string` | — | — | Optional | `excluded` | — |

## PluginsSettings

Module `tai42_skeleton.plugins.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `STUDIO_DIST_PATH` | `string` | — | — | Optional | `hot` | — |

## PrometheusSettings

Module `tai42_toolbox._internal.extensions.prometheus_counters`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `PROMETHEUS_METRICS_NAMESPACE` | `string` | `"tai"` | — | Optional | `hot` | — |
| `PROMETHEUS_RUNTIME` | `string` | `"main"` | — | Optional | `hot` | — |

## ProxySettings

Module `tai42_toolbox._internal.extensions.proxy_context`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `PROXY_POOL` | `array` | `[]` | — | Optional | `hot` | — |
| `PROXY_ALLOW_CALLER_URLS` | `boolean` | `false` | — | Optional | `hot` | — |
| `PROXY_CONNECT_TIMEOUT` | `integer` | `30` | — | Optional | `hot` | — |

## RateLimitRedisSettings

Module `tai42_skeleton.settings.rate_limit`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_RATE_LIMIT_SOCKET_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `TAI_RATE_LIMIT_SOCKET_CONNECT_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `TAI_RATE_LIMIT_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `TAI_RATE_LIMIT_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `TAI_RATE_LIMIT_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `TAI_RATE_LIMIT_REDIS_MAX_CONNECTIONS` | `integer` | `10` | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `TAI_RATE_LIMIT_DECODE_RESPONSES` | `boolean` | `true` | — | Optional | `hot` | — |

## RateLimitSettings

Module `tai42_skeleton.settings.rate_limit`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| — | `object` | — | — | Optional | — | Grouped settings — see [RateLimitRedisSettings](#ratelimitredissettings). |
| `TAI_RATE_LIMIT_KEY_PREFIX` | `string` | `"ratelimit:"` | — | Optional | `hot` | — |
| `TAI_RATE_LIMIT_DEFAULT_ENABLED` | `boolean` | `true` | — | Optional | `hot` | — |
| `TAI_RATE_LIMIT_DEFAULT_LIMIT` | `integer` | `600` | — | Optional | `hot` | — |
| `TAI_RATE_LIMIT_DEFAULT_BURST` | `integer` | `120` | — | Optional | `hot` | — |
| `TAI_RATE_LIMIT_FAMILIES` | `object` | `{}` | — | Optional | `hot` | — |

## RedisIdentityConnectionSettings

Module `tai42_identity_redis.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_IDENTITY_SOCKET_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `TAI_IDENTITY_SOCKET_CONNECT_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `TAI_IDENTITY_RETRY_ON_TIMEOUT` | `boolean` | `true` | — | Optional | `hot` | — |
| `TAI_IDENTITY_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `TAI_IDENTITY_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `TAI_IDENTITY_REDIS_MAX_CONNECTIONS` | `integer` | `10` | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `TAI_IDENTITY_DECODE_RESPONSES` | `boolean` | `true` | — | Optional | `hot` | — |

## RedisIdentitySettings

Module `tai42_identity_redis.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_IDENTITY_KEY_PREFIX` | `string` | `"ac:key:"` | — | Optional | `hot` | — |
| — | `object` | — | — | Optional | — | Grouped settings — see [RedisIdentityConnectionSettings](#redisidentityconnectionsettings). |

## RqRedisSettings

Module `tai42_backend_rq.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `RQ_SOCKET_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `RQ_SOCKET_CONNECT_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `RQ_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `RQ_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `RQ_REDIS_URL` | `string` | `"redis://localhost:6379/0"` | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `RQ_REDIS_MAX_CONNECTIONS` | `integer` | — | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |

## RqSettings

Module `tai42_backend_rq.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `RQ_MANIFEST_KEY` | `string` | `"MANIFEST_KEY"` | — | Optional | `recycle` | — |
| `RQ_TASK_TIMEOUT` | `integer` | `300` | — | Optional | `recycle` | The dispatch's job budget in seconds: the longest a dispatched job may run on the worker, and how long a synchronous dispatch waits for its result. Worker-side limits are bound when the worker starts, so a change converges through a process recycle. |
| `RQ_TOOL_NAME_ARG` | `string` | `"backend_tool_name"` | — | Optional | `recycle` | — |
| — | `object` | — | — | Optional | — | Grouped settings — see [RqRedisSettings](#rqredissettings). |
| `RQ_RQ_PREFIX` | `string` | `"rq:"` | — | Optional | `hot` | — |
| `RQ_QUEUE_NAME` | `string` | `"default"` | — | Optional | `hot` | — |

## RunIndexSettings

Module `tai42_skeleton.runs.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_RUNS_INDEX_RETENTION_DAYS` | `integer` | — | — | Optional | `hot` | — |
| `TAI_RUNS_INDEX_MAX_PAGE_SIZE` | `integer` | `200` | — | Optional | `hot` | — |

## S3Settings

Module `tai42_storage_s3.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `STORAGE_S3_BUCKET` | `string` | — | — | Optional | `hot` | — |
| `STORAGE_S3_ENDPOINT` | `string` | — | — | Optional | `hot` | — |
| `STORAGE_S3_ACCESS_KEY` | `string` | — | — | Optional | `hot` | Secret. |
| `STORAGE_S3_SECRET_KEY` | `string` | — | — | Optional | `hot` | Secret. |
| `STORAGE_S3_SECURE` | `boolean` | `true` | — | Optional | `hot` | — |
| `STORAGE_S3_REGION` | `string` | `"us-east-1"` | — | Optional | `hot` | — |
| `STORAGE_S3_VERIFY_SSL` | `boolean` | `true` | — | Optional | `hot` | — |
| `STORAGE_S3_CONNECT_TIMEOUT` | `integer` | `5` | — | Optional | `hot` | — |
| `STORAGE_S3_READ_TIMEOUT` | `integer` | `30` | — | Optional | `hot` | — |
| `STORAGE_S3_ADDRESSING_STYLE` | `string` | `"auto"` | — | Optional | `hot` | — |
| `STORAGE_S3_REQUEST_CHECKSUM_CALCULATION` | `string` | — | — | Optional | `hot` | — |
| `STORAGE_S3_CHECKSUM_ALGORITHM` | `string` | — | — | Optional | `hot` | — |

## SamplingSettings

Module `tai42_skeleton.tools.sampling_settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_SAMPLING_MAX_TOKENS_PER_CALL` | `integer` | `32768` | — | Optional | `hot` | — |
| `TAI_SAMPLING_MAX_CALLS_PER_INVOCATION` | `integer` | `20` | — | Optional | `hot` | — |

## SandboxLocalSettings

Module `tai42_sandbox_local.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `SANDBOX_LOCAL_REAP_INTERVAL_SECONDS` | `integer` | `300` | — | Optional | `hot` | — |
| `SANDBOX_LOCAL_EXEC_DEFAULT_TIMEOUT_SECONDS` | `integer` | `300` | — | Optional | `hot` | — |
| `SANDBOX_LOCAL_ROOT` | `string` | `"/var/lib/tai-sandbox-local"` | — | Optional | `recycle` | — |
| `SANDBOX_LOCAL_BASE_PATH` | `string` | `"/usr/local/bin:/usr/bin:/bin"` | — | Optional | `hot` | — |

## SetupSettings

Module `tai42_skeleton.access_control.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_SETUP_TOKEN` | `string` | — | — | Optional | `hot` | Secret. |
| `TAI_SETUP_OPEN` | `boolean` | `false` | — | Optional | `hot` | — |

## SlackRedisSettings

Module `tai42_channel_slack.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CHANNEL_SLACK_SOCKET_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `CHANNEL_SLACK_SOCKET_CONNECT_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `CHANNEL_SLACK_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `CHANNEL_SLACK_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `CHANNEL_SLACK_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `CHANNEL_SLACK_REDIS_MAX_CONNECTIONS` | `integer` | — | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `CHANNEL_SLACK_DECODE_RESPONSES` | `boolean` | `true` | — | Optional | `hot` | — |

## SlackSettings

Module `tai42_channel_slack.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CHANNEL_SLACK_BOT_TOKEN` | `string` | — | — | Optional | `hot` | Secret. |
| `CHANNEL_SLACK_SIGNING_SECRET` | `string` | — | — | Optional | `hot` | Secret. |
| `CHANNEL_SLACK_BOT_USER_ID` | `string` | — | — | Optional | `hot` | — |
| `CHANNEL_SLACK_ALLOWED_RECIPIENTS` | `array` | `[]` | — | Optional | `hot` | — |
| `CHANNEL_SLACK_DEFAULT_RECIPIENT` | `string` | — | — | Optional | `hot` | — |
| `CHANNEL_SLACK_API_BASE_URL` | `string` | `"https://slack.com/api"` | — | Optional | `hot` | — |
| `CHANNEL_SLACK_HTTP_TIMEOUT_SECONDS` | `number` | `30` | — | Optional | `hot` | — |

## StatesSettings

Module `tai42_skeleton.states.db`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `STATES_OP_RETENTION_DAYS` | `integer` | `30` | — | Optional | `hot` | — |
| `STATES_DEFAULT_RETENTION_DAYS` | `integer` | — | — | Optional | `hot` | — |
| `STATES_OUTBOX_SWEEP_SECONDS` | `number` | `5.0` | — | Optional | `hot` | — |
| `STATES_OUTBOX_CLAIM_LEASE_SECONDS` | `number` | `60.0` | — | Optional | `hot` | — |
| `STATES_OUTBOX_MAX_ATTEMPTS` | `integer` | `5` | — | Optional | `hot` | — |
| `STATES_OUTBOX_RETRY_BASE_SECONDS` | `number` | `1.0` | — | Optional | `hot` | — |
| `STATES_OUTBOX_RETRY_CAP_SECONDS` | `number` | `60.0` | — | Optional | `hot` | — |
| `STATES_OUTBOX_DRAIN_POLL_SECONDS` | `number` | `0.05` | — | Optional | `hot` | — |
| `STATES_OUTBOX_DRAIN_TIMEOUT_SECONDS` | `number` | `30.0` | — | Optional | `hot` | — |
| `STATES_OUTBOX_SHUTDOWN_GRACE_SECONDS` | `number` | `20.0` | — | Optional | `hot` | — |

## StripeSettings

Module `tai42_tools_stripe._internal.tools.stripe_client`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `STRIPE_SECRET_KEY` | `string` | — | — | Optional | `hot` | Secret. |
| `STRIPE_API_BASE` | `string` | `"https://api.stripe.com"` | — | Optional | `hot` | — |
| `STRIPE_REQUEST_TIMEOUT_SECONDS` | `number` | `20` | — | Optional | `hot` | — |
| `STRIPE_RECONCILE_ANSWER_INTERVAL_SECONDS` | `number` | `1.2` | — | Optional | `hot` | — |
| `TAI_BRIDGE_CALLBACK_SECRET` | `string` | — | — | Optional | `hot` | Secret. |

## SubMcpRedisSettings

Module `tai42_skeleton.sub_mcp.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `SUB_MCP_SOCKET_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `SUB_MCP_SOCKET_CONNECT_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `SUB_MCP_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `SUB_MCP_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `SUB_MCP_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `SUB_MCP_REDIS_MAX_CONNECTIONS` | `integer` | — | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `SUB_MCP_DECODE_RESPONSES` | `boolean` | `true` | — | Optional | `hot` | — |

## SubMcpSettings

Module `tai42_skeleton.sub_mcp.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| — | `object` | — | — | Optional | — | Grouped settings — see [SubMcpRedisSettings](#submcpredissettings). |
| `SUB_MCP_PREFIX` | `string` | `"sub_mcp"` | — | Optional | `hot` | — |

## SummarizationMiddlewareSettings

Module `tai42_kit.llm.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `SUMMARIZATION_MIDDLEWARE_TRIGGER_TOKENS` | `integer` | `5000` | — | Optional | `hot` | — |
| `SUMMARIZATION_MIDDLEWARE_KEEP_MESSAGES` | `integer` | `20` | — | Optional | `hot` | — |
| `SUMMARIZATION_MIDDLEWARE_TRIM_TOKENS_TO_SUMMARIZE` | `integer` | `4000` | — | Optional | `hot` | — |
| `SUMMARIZATION_MIDDLEWARE_SUMMARY_PROMPT` | `object` | — | — | Optional | `hot` | — |

## TelegramCorrelationSettings

Module `tai42_channel_telegram.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CHANNEL_TELEGRAM_SOCKET_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `CHANNEL_TELEGRAM_SOCKET_CONNECT_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `CHANNEL_TELEGRAM_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `CHANNEL_TELEGRAM_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `CHANNEL_TELEGRAM_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `CHANNEL_TELEGRAM_REDIS_MAX_CONNECTIONS` | `integer` | — | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `CHANNEL_TELEGRAM_DECODE_RESPONSES` | `boolean` | `true` | — | Optional | `hot` | — |

## TelegramSettings

Module `tai42_channel_telegram.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CHANNEL_TELEGRAM_BOT_TOKEN` | `string` | — | — | Optional | `hot` | Secret. |
| `CHANNEL_TELEGRAM_ALLOWED_RECIPIENTS` | `array` | `[]` | — | Optional | `hot` | — |
| `CHANNEL_TELEGRAM_DEFAULT_RECIPIENT` | `string` | — | — | Optional | `hot` | — |
| `CHANNEL_TELEGRAM_WEBHOOK_SECRET` | `string` | — | — | Optional | `hot` | Secret. |
| `CHANNEL_TELEGRAM_PUBLIC_BASE_URL` | `string` | — | — | Optional | `hot` | — |
| `CHANNEL_TELEGRAM_API_BASE_URL` | `string` | `"https://api.telegram.org"` | — | Optional | `hot` | — |
| `CHANNEL_TELEGRAM_HTTP_TIMEOUT_SECONDS` | `number` | `30` | — | Optional | `hot` | — |
| `CHANNEL_TELEGRAM_OPTION_TAP_TTL_SECONDS` | `integer` | `86400` | — | Optional | `hot` | — |

## TemplateCacheSettings

Module `tai42_skeleton.template.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TEMPLATE_CACHE_TTL` | `integer` | `300` | — | Optional | `hot` | — |
| `TEMPLATE_CACHE_MAX_SIZE` | `integer` | `1024` | — | Optional | `hot` | — |

## ToolRunsRedisSettings

Module `tai42_skeleton.routers.tool_runs_settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_TOOL_RUNS_SOCKET_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `TAI_TOOL_RUNS_SOCKET_CONNECT_TIMEOUT` | `number` | `5` | — | Optional | `hot` | — |
| `TAI_TOOL_RUNS_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `TAI_TOOL_RUNS_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `TAI_TOOL_RUNS_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `TAI_TOOL_RUNS_REDIS_MAX_CONNECTIONS` | `integer` | `10` | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `TAI_TOOL_RUNS_DECODE_RESPONSES` | `boolean` | `true` | — | Optional | `hot` | — |

## ToolRunsSettings

Module `tai42_skeleton.routers.tool_runs_settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| — | `object` | — | — | Optional | — | Grouped settings — see [ToolRunsRedisSettings](#toolrunsredissettings). |
| `TAI_TOOL_RUNS_KEY_PREFIX` | `string` | `"tool_runs:"` | — | Optional | `hot` | — |
| `TAI_TOOL_RUNS_RECENT_RUNS_LIMIT` | `integer` | `50` | — | Optional | `hot` | — |
| `TAI_TOOL_RUNS_RESULT_TTL_SECONDS` | `integer` | `86400` | — | Optional | `hot` | — |
| `TAI_TOOL_RUNS_LIVENESS_TTL_SECONDS` | `integer` | `30` | — | Optional | `hot` | — |
| `TAI_TOOL_RUNS_MAX_CONCURRENT_RUNS` | `integer` | `32` | — | Optional | `hot` | — |
| `TAI_TOOL_RUNS_SHUTDOWN_DRAIN_SECONDS` | `number` | `10` | — | Optional | `hot` | — |

## TrimmingMiddlewareSettings

Module `tai42_kit.llm.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TRIMMING_MIDDLEWARE_STRATEGY` | `string` | `"last"` | — | Optional | `hot` | — |
| `TRIMMING_MIDDLEWARE_MAX_TOKENS` | `integer` | `5000` | — | Optional | `hot` | — |
| `TRIMMING_MIDDLEWARE_INCLUDE_SYSTEM` | `boolean` | `true` | — | Optional | `hot` | — |
| `TRIMMING_MIDDLEWARE_ALLOW_PARTIAL` | `boolean` | `false` | — | Optional | `hot` | — |
| `TRIMMING_MIDDLEWARE_END_ON` | `string` | — | — | Optional | `hot` | — |
| `TRIMMING_MIDDLEWARE_START_ON` | `string` | — | — | Optional | `hot` | — |

## TurnSettings

Module `tai42_skeleton.settings.turn`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_TURN_TIMEOUT_SECONDS` | `number` | — | — | Optional | `hot` | Wall-clock budget in seconds for one synchronous turn; unset = unbounded. On expiry the turn is cancelled with a typed turn-exceeded error; a turn killed while parked on an unanswered question names that question in the error. |

## TwilioRedisSettings

Module `tai42_channel_twilio.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CHANNEL_TWILIO_SOCKET_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `CHANNEL_TWILIO_SOCKET_CONNECT_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `CHANNEL_TWILIO_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `CHANNEL_TWILIO_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `CHANNEL_TWILIO_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `CHANNEL_TWILIO_REDIS_MAX_CONNECTIONS` | `integer` | — | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `CHANNEL_TWILIO_DECODE_RESPONSES` | `boolean` | `true` | — | Optional | `hot` | — |

## TwilioSettings (tai42-channel-twilio)

Module `tai42_channel_twilio.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CHANNEL_TWILIO_ACCOUNT_SID` | `string` | — | — | Optional | `hot` | — |
| `CHANNEL_TWILIO_AUTH_TOKEN` | `string` | — | — | Optional | `hot` | Secret. |
| `CHANNEL_TWILIO_FROM` | `string` | — | — | Optional | `hot` | — |
| `CHANNEL_TWILIO_ALLOWED_RECIPIENTS` | `array` | `[]` | — | Optional | `hot` | — |
| `CHANNEL_TWILIO_DEFAULT_RECIPIENT` | `string` | — | — | Optional | `hot` | — |
| `CHANNEL_TWILIO_API_BASE_URL` | `string` | `"https://api.twilio.com/2010-04-01"` | — | Optional | `hot` | — |
| `CHANNEL_TWILIO_HTTP_TIMEOUT_SECONDS` | `number` | `30.0` | — | Optional | `hot` | — |
| `CHANNEL_TWILIO_DEDUPE_TTL` | `integer` | `172800` | — | Optional | `hot` | — |

## TwilioSettings (tai42-tools-twilio)

Module `tai42_tools_twilio._internal.tools.twilio_client`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CHANNEL_TWILIO_ACCOUNT_SID` | `string` | — | — | Optional | `hot` | — |
| `CHANNEL_TWILIO_AUTH_TOKEN` | `string` | — | — | Optional | `hot` | Secret. |
| `CHANNEL_TWILIO_API_BASE_URL` | `string` | `"https://api.twilio.com/2010-04-01"` | — | Optional | `hot` | — |
| `CHANNEL_TWILIO_HTTP_TIMEOUT_SECONDS` | `number` | `30.0` | — | Optional | `hot` | — |

## UrlGuardSettings

Module `tai42_kit.net.url_guard`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `TAI_URL_GUARD_ENABLED` | `boolean` | `true` | — | Optional | `hot` | — |
| `TAI_URL_GUARD_ALLOW_CIDRS` | `array` | `[]` | — | Optional | `hot` | — |
| `TAI_URL_GUARD_MAX_RESPONSE_BYTES` | `integer` | `104857600` | — | Optional | `hot` | — |
| `TAI_URL_GUARD_MAX_REDIRECTS` | `integer` | `20` | — | Optional | `hot` | — |

## WebRedisSettings

Module `tai42_channel_web.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CHANNEL_WEB_SOCKET_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `CHANNEL_WEB_SOCKET_CONNECT_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `CHANNEL_WEB_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `CHANNEL_WEB_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `CHANNEL_WEB_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `CHANNEL_WEB_REDIS_MAX_CONNECTIONS` | `integer` | — | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `CHANNEL_WEB_DECODE_RESPONSES` | `boolean` | `true` | — | Optional | `hot` | — |

## WebSettings

Module `tai42_channel_web.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CHANNEL_WEB_HTTP_TIMEOUT_SECONDS` | `number` | `30.0` | — | Optional | `hot` | — |
| `CHANNEL_WEB_TRANSCRIPT_MAX_ENTRIES` | `integer` | `1000` | — | Optional | `hot` | — |
| `CHANNEL_WEB_BACKLOG_BATCH_ENTRIES` | `integer` | `200` | — | Optional | `hot` | — |
| `CHANNEL_WEB_TRANSCRIPT_TTL_SECONDS` | `integer` | `2592000` | — | Optional | `hot` | — |
| `CHANNEL_WEB_BLOCKING_GRACE_SECONDS` | `number` | `5.0` | — | Optional | `hot` | — |
| `CHANNEL_WEB_KEEPALIVE_SECONDS` | `integer` | `15` | — | Optional | `hot` | — |
| `CHANNEL_WEB_SESSION_COOKIE_SECURE` | `boolean` | `true` | — | Optional | `hot` | — |
| `CHANNEL_WEB_SESSION_TTL_SECONDS` | `integer` | `2592000` | — | Optional | `hot` | — |
| `CHANNEL_WEB_SESSION_PENDING_TTL_SECONDS` | `integer` | `600` | — | Optional | `hot` | — |
| `CHANNEL_WEB_MAX_ANSWER_RESTORES` | `integer` | `5` | — | Optional | `hot` | — |
| `CHANNEL_WEB_MAX_BODY_BYTES` | `integer` | `65536` | — | Optional | `hot` | — |
| `CHANNEL_WEB_MAX_STREAMS_PER_VISITOR` | `integer` | `4` | — | Optional | `hot` | — |
| `CHANNEL_WEB_MAX_STREAMS_TOTAL` | `integer` | `500` | — | Optional | `hot` | — |
| `CHANNEL_WEB_PAGE_TITLE` | `string` | `"Chat"` | — | Optional | `hot` | — |
| `CHANNEL_WEB_STORE_OFF_TITLE` | `string` | `"Chat is unavailable"` | — | Optional | `hot` | — |
| `CHANNEL_WEB_STORE_OFF_TEXT` | `string` | `"This chat is not switched on. Please contact the site owner."` | — | Optional | `hot` | — |
| `CHANNEL_WEB_ENTRY_ATTEMPTS_PER_WINDOW` | `integer` | `10` | — | Optional | `hot` | — |
| `CHANNEL_WEB_ENTRY_THROTTLE_WINDOW_SECONDS` | `integer` | `300` | — | Optional | `hot` | — |
| `CHANNEL_WEB_MAX_ATTACHMENTS_PER_MESSAGE` | `integer` | `10` | — | Optional | `hot` | — |

## WebhookIngressSettings

Module `tai42_skeleton.webhooks.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `WEBHOOK_INGRESS_MAX_BODY_BYTES` | `integer` | `65536` | — | Optional | `hot` | — |

## WhatsAppRedisSettings

Module `tai42_channel_whatsapp.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CHANNEL_WHATSAPP_SOCKET_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `CHANNEL_WHATSAPP_SOCKET_CONNECT_TIMEOUT` | `number` | — | — | Optional | `hot` | — |
| `CHANNEL_WHATSAPP_RETRY_ON_TIMEOUT` | `boolean` | `false` | — | Optional | `hot` | — |
| `CHANNEL_WHATSAPP_RETRY_ATTEMPTS` | `integer` | `0` | — | Optional | `hot` | — |
| `CHANNEL_WHATSAPP_REDIS_URL` | `string` | — | [`TAI_DEFAULT_REDIS_URL`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `CHANNEL_WHATSAPP_REDIS_MAX_CONNECTIONS` | `integer` | — | [`TAI_DEFAULT_REDIS_MAX_CONNECTIONS`](/concepts/config-and-secrets#default-connection-namespace) | Optional | `hot` | — |
| `CHANNEL_WHATSAPP_DECODE_RESPONSES` | `boolean` | `true` | — | Optional | `hot` | — |

## WhatsAppSettings

Module `tai42_channel_whatsapp.settings`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CHANNEL_WHATSAPP_ACCESS_TOKEN` | `string` | — | — | Optional | `hot` | Secret. |
| `CHANNEL_WHATSAPP_APP_SECRET` | `string` | — | — | Optional | `hot` | Secret. |
| `CHANNEL_WHATSAPP_VERIFY_TOKEN` | `string` | — | — | Optional | `hot` | Secret. |
| `CHANNEL_WHATSAPP_API_BASE_URL` | `string` | `"https://graph.facebook.com/v23.0"` | — | Optional | `hot` | — |
| `CHANNEL_WHATSAPP_DEFAULT_PHONE_NUMBER_ID` | `string` | — | — | Optional | `hot` | — |
| `CHANNEL_WHATSAPP_WABA_ID` | `string` | — | — | Optional | `hot` | — |
| `CHANNEL_WHATSAPP_FLOW_PRIVATE_KEY` | `string` | — | — | Optional | `hot` | Secret. |
| `CHANNEL_WHATSAPP_FLOW_PRIVATE_KEY_PASSPHRASE` | `string` | — | — | Optional | `hot` | Secret. |
| `CHANNEL_WHATSAPP_FLOW_ENDPOINT_URI` | `string` | — | — | Optional | `hot` | — |
| `CHANNEL_WHATSAPP_ALLOWED_RECIPIENTS` | `array` | `[]` | — | Optional | `hot` | — |
| `CHANNEL_WHATSAPP_HTTP_TIMEOUT_SECONDS` | `number` | `30.0` | — | Optional | `hot` | — |
| `CHANNEL_WHATSAPP_DEDUPE_TTL` | `integer` | `172800` | — | Optional | `hot` | — |
| `CHANNEL_WHATSAPP_TEMPLATE_CONTACT_WINDOW_DAYS` | `integer` | `30` | — | Optional | `hot` | — |

## WhatsAppToolsSettings

Module `tai42_tools_whatsapp._internal.tools.whatsapp_client`.

| Env var | Type | Default | Fallback | Required | Reload | Description |
| - | - | - | - | - | - | - |
| `CHANNEL_WHATSAPP_ACCESS_TOKEN` | `string` | — | — | Optional | `hot` | Secret. |
| `CHANNEL_WHATSAPP_WABA_ID` | `string` | — | — | Optional | `hot` | — |
| `CHANNEL_WHATSAPP_API_BASE_URL` | `string` | `"https://graph.facebook.com/v23.0"` | — | Optional | `hot` | — |
| `CHANNEL_WHATSAPP_HTTP_TIMEOUT_SECONDS` | `number` | `30.0` | — | Optional | `hot` | — |


# Components
Source: https://docs.tai42.ai/reference/studio-sdk/components

The design-system components — inputs, layout, tables, pickers, and disclosure primitives.

The design-system components — inputs, layout, tables, pickers, and disclosure primitives.

## AgentsIcon

```ts theme={null}
const AgentsIcon: IconComponent
```

Agents: a bot — antenna, panel head with eyes and mouth, side ports.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## AlertTriangleIcon

```ts theme={null}
const AlertTriangleIcon: IconComponent
```

Warning.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## ArrowDownIcon

```ts theme={null}
const ArrowDownIcon: IconComponent
```

Move the item one place later in an ordered list.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## ArrowLeftIcon

```ts theme={null}
const ArrowLeftIcon: IconComponent
```

Back / previous.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## ArrowUpIcon

```ts theme={null}
const ArrowUpIcon: IconComponent
```

Move the item one place earlier in an ordered list.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## BADGES\_NOTE

```ts theme={null}
const BADGES_NOTE: "Declared capability labels — informational only. They describe what the tool touches; the server never enforces them."
```

The shared informational note every badge surface carries: declared, never enforced.

## Badge

```ts theme={null}
function Badge(props: BadgeProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `children` | `ReactNode` | — |
| `variant?` | `string` | — |

**Related:** [BadgeProps](/reference/studio-sdk/components#badgeprops)

## BadgeProps

```ts theme={null}
interface BadgeProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `children` | `ReactNode` | — |
| `variant?` | `string` | — |

## Button

```ts theme={null}
function Button(props: ButtonActionProps | LinkButtonProps): Element
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `props` | `ButtonActionProps \| LinkButtonProps` | — | — |

**Related:** [LinkButtonProps](/reference/studio-sdk/components#linkbuttonprops)

## ButtonProps

```ts theme={null}
interface ButtonProps extends ButtonVariantProps, ButtonHTMLAttributes<HTMLButtonElement>
```

The ACTION form of `Button`: button attributes, no anchor ones.

This stays an INTERFACE extending `ButtonHTMLAttributes<HTMLButtonElement>`
because it is published plugin API: a plugin may write
`interface MyButton extends ButtonProps {}` (a union cannot be extended —
TS2312) and may hand a `ButtonProps` value to a slot typed as plain
`ButtonHTMLAttributes<HTMLButtonElement>` (a union including anchor attributes
is not assignable — TS2322). The link form is the ADDITIVE `LinkButtonProps`,
and `Button` accepts either.

It declares NO `href` member. `href?: undefined` here would make
`interface MyButton extends ButtonProps { href: string }` a TS2430
("incorrectly extends"), which is a narrowing of a surface that is additive
only. The discriminant `Button` narrows on lives on `ButtonActionProps`.

**Properties**

| Property | Type | Description |
| - | - | - |
| `ref?` | `Ref<HTMLButtonElement>` | A consumer ref for the `<button>`; the prop spread forwards it. |
| `variant?` | `ButtonVariant` | — |

**Related:** [ButtonVariant](/reference/studio-sdk/components#buttonvariant)

## ButtonVariant

```ts theme={null}
type ButtonVariant = "primary" | "secondary" | "ghost" | "danger"
```

## Card

```ts theme={null}
function Card(props: CardProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `children` | `ReactNode` | — |
| `className?` | `string` | — |
| `interactive?` | `boolean` | Opt in to the hover/focus lift. A card that is not itself an affordance stays flat. |
| `ref?` | `Ref<HTMLDivElement>` | A consumer ref for the card element itself. |
| `style?` | `CSSProperties` | — |

**Related:** [CardProps](/reference/studio-sdk/components#cardprops)

## CardProps

```ts theme={null}
interface CardProps extends SurfaceProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `children` | `ReactNode` | — |
| `className?` | `string` | — |
| `interactive?` | `boolean` | Opt in to the hover/focus lift. A card that is not itself an affordance stays flat. |
| `ref?` | `Ref<HTMLDivElement>` | A consumer ref for the card element itself. |
| `style?` | `CSSProperties` | — |

## CheckCircleIcon

```ts theme={null}
const CheckCircleIcon: IconComponent
```

Success.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## CheckIcon

```ts theme={null}
const CheckIcon: IconComponent
```

A bare tick, for selection and confirmation.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## Checkbox

```ts theme={null}
function Checkbox(props: CheckboxProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `aria-label?` | `string` | Accessible name for a checkbox with no visible `label` (e.g. a table cell). An enclosing `Field` wins where both are given — it names the box from visible text, and `aria-label` would override that native label and leave the visible text out of the accessible name (WCAG 2.5.3). |
| `checked?` | `boolean \| "indeterminate"` | `'indeterminate'` is the MIXED state a parent box wears while only some of the children it governs are checked. Radix reports it as `aria-checked="mixed"`; clicking it resolves to checked, which is why the change callback stays boolean. |
| `defaultChecked?` | `boolean` | — |
| `disabled?` | `boolean` | — |
| `label?` | `string` | — |
| `name?` | `string` | — |
| `onCheckedChange?` | `(checked: boolean) => void` | — |
| `value?` | `string` | — |

**Related:** [CheckboxProps](/reference/studio-sdk/components#checkboxprops)

## CheckboxProps

```ts theme={null}
interface CheckboxProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `aria-label?` | `string` | Accessible name for a checkbox with no visible `label` (e.g. a table cell). An enclosing `Field` wins where both are given — it names the box from visible text, and `aria-label` would override that native label and leave the visible text out of the accessible name (WCAG 2.5.3). |
| `checked?` | `boolean \| "indeterminate"` | `'indeterminate'` is the MIXED state a parent box wears while only some of the children it governs are checked. Radix reports it as `aria-checked="mixed"`; clicking it resolves to checked, which is why the change callback stays boolean. |
| `defaultChecked?` | `boolean` | — |
| `disabled?` | `boolean` | — |
| `label?` | `string` | — |
| `name?` | `string` | — |
| `onCheckedChange?` | `(checked: boolean) => void` | — |
| `value?` | `string` | — |

## ChevronDownIcon

```ts theme={null}
const ChevronDownIcon: IconComponent
```

Expand / collapse affordance.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## ChevronRightIcon

```ts theme={null}
const ChevronRightIcon: IconComponent
```

Disclosure / breadcrumb separator.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## ChipGroup

```ts theme={null}
function ChipGroup(props: ChipGroupProps): ReactNode
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `props` | `ChipGroupProps` | — | — |

**Related:** [ChipGroupProps](/reference/studio-sdk/components#chipgroupprops)

## ChipGroupProps

```ts theme={null}
type ChipGroupProps = { disabled?: boolean; mode: "single"; onValueChange: (value: string) => void; options: readonly ChipOption[]; value: string } | { disabled?: boolean; mode: "multi"; onValueChange: (value: readonly string[]) => void; options: readonly ChipOption[]; value: readonly string[] }
```

**Related:** [ChipOption](/reference/studio-sdk/components#chipoption)

## ChipOption

```ts theme={null}
interface ChipOption
```

One selectable chip: its answer `value` and the visible `label`.

**Properties**

| Property | Type | Description |
| - | - | - |
| `disabled?` | `boolean` | — |
| `label` | `string` | — |
| `value` | `string` | — |

## CloseIcon

```ts theme={null}
const CloseIcon: IconComponent
```

Dismiss.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## CodeBlock

```ts theme={null}
function CodeBlock(props: CodeBlockProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `code` | `string` | — |
| `language?` | `string` | Optional language label, shown as a caption; purely informational. |

**Related:** [CodeBlockProps](/reference/studio-sdk/components#codeblockprops)

## CodeBlockProps

```ts theme={null}
interface CodeBlockProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `code` | `string` | — |
| `language?` | `string` | Optional language label, shown as a caption; purely informational. |

## CompletionInput

```ts theme={null}
function CompletionInput(props: CompletionInputProps): ReactNode
```

A completion-backed text input. Suggestions refresh on every edit (a
per-request sequence guard drops a stale response) and render as an ARIA
listbox; selecting an option fills the field and clears the list.

**Props**

| Prop | Type | Description |
| - | - | - |
| `fetchCompletions` | `(value: string) => Promise<readonly string[]>` | Fetch argument completions for the current input value. |
| `onChange` | `(value: string) => void` | — |
| `onError?` | `(error: unknown) => void` | Surfaced (not swallowed) when a completion fetch fails. |
| `placeholder?` | `string` | — |
| `value` | `string` | — |

**Related:** [CompletionInputProps](/reference/studio-sdk/components#completioninputprops)

## CompletionInputProps

```ts theme={null}
interface CompletionInputProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `fetchCompletions` | `(value: string) => Promise<readonly string[]>` | Fetch argument completions for the current input value. |
| `onChange` | `(value: string) => void` | — |
| `onError?` | `(error: unknown) => void` | Surfaced (not swallowed) when a completion fetch fails. |
| `placeholder?` | `string` | — |
| `value` | `string` | — |

## ConfirmDialog

```ts theme={null}
function ConfirmDialog(props: ConfirmDialogProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `cancelLabel?` | `string` | The cancel button's label; defaults to `Cancel`. Set it when the negative choice reads better as a specific verb (e.g. `Keep existing`). |
| `children` | `ReactNode` | The prompt body — what the operator is confirming. |
| `confirmLabel` | `string` | The confirm button's resting label (e.g. `Delete scope`). |
| `confirmVariant?` | `"primary" \| "danger"` | — |
| `disabledNote?` | `ReactNode` | A muted node shown in the error slot INSTEAD of the loud `ErrorState`, for the OFF (disabled-feature) case: the action's store is not configured, so the failure is a state, not an error. When set it takes the error slot AND disables the confirm button — the action can only refuse, so there is nothing to retry. |
| `error?` | `string \| Error \| null` | The failed action's error, rendered loudly; omit/`null` while there is none.  A thrown `Error` or the message on its own — `Field`'s `error` is a plain string, and the two props sit side by side on a form, so this one accepts that spelling too rather than making one surface's `error` unassignable to the other's. |
| `isPending` | `boolean` | — |
| `onClose` | `() => void` | — |
| `onConfirm` | `() => void` | — |
| `pendingLabel` | `string` | The Spinner's accessible label while the action runs (e.g. `Deleting`). |
| `title` | `string` | — |

**Related:** [ConfirmDialogProps](/reference/studio-sdk/components#confirmdialogprops)

## ConfirmDialogProps

```ts theme={null}
interface ConfirmDialogProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `cancelLabel?` | `string` | The cancel button's label; defaults to `Cancel`. Set it when the negative choice reads better as a specific verb (e.g. `Keep existing`). |
| `children` | `ReactNode` | The prompt body — what the operator is confirming. |
| `confirmLabel` | `string` | The confirm button's resting label (e.g. `Delete scope`). |
| `confirmVariant?` | `"primary" \| "danger"` | — |
| `disabledNote?` | `ReactNode` | A muted node shown in the error slot INSTEAD of the loud `ErrorState`, for the OFF (disabled-feature) case: the action's store is not configured, so the failure is a state, not an error. When set it takes the error slot AND disables the confirm button — the action can only refuse, so there is nothing to retry. |
| `error?` | `string \| Error \| null` | The failed action's error, rendered loudly; omit/`null` while there is none.  A thrown `Error` or the message on its own — `Field`'s `error` is a plain string, and the two props sit side by side on a form, so this one accepts that spelling too rather than making one surface's `error` unassignable to the other's. |
| `isPending` | `boolean` | — |
| `onClose` | `() => void` | — |
| `onConfirm` | `() => void` | — |
| `pendingLabel` | `string` | The Spinner's accessible label while the action runs (e.g. `Deleting`). |
| `title` | `string` | — |

## ConnectorsIcon

```ts theme={null}
const ConnectorsIcon: IconComponent
```

Connectors: a two-pin power plug on its lead.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## ConversationsIcon

```ts theme={null}
const ConversationsIcon: IconComponent
```

Conversations: one speech bubble holding transcript lines.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## CopyField

```ts theme={null}
function CopyField(props: CopyFieldProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `caption?` | `string` | — |
| `idPrefix?` | `string` | — |
| `label?` | `string` | — |
| `value` | `string` | — |

**Related:** [CopyFieldProps](/reference/studio-sdk/components#copyfieldprops)

## CopyFieldProps

```ts theme={null}
interface CopyFieldProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `caption?` | `string` | — |
| `idPrefix?` | `string` | — |
| `label?` | `string` | — |
| `value` | `string` | — |

## CopyIcon

```ts theme={null}
const CopyIcon: IconComponent
```

Copy to clipboard: a sheet duplicated behind another.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## DEFAULT\_DATE\_RANGE\_PRESETS

```ts theme={null}
const DEFAULT_DATE_RANGE_PRESETS: readonly DateRangePreset[]
```

The presets a picker offers when the caller names none.

**Related:** [DateRangePreset](/reference/studio-sdk/components#daterangepreset)

## DashboardIcon

```ts theme={null}
const DashboardIcon: IconComponent
```

Observability: a dial gauge — arc, base and needle.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## DatabaseIcon

```ts theme={null}
const DatabaseIcon: IconComponent
```

States: a stacked-disk cylinder — one document store per subject.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## DateRangePicker

```ts theme={null}
function DateRangePicker(props: DateRangePickerProps): ReactNode
```

The range control: a row of preset chips over the two `datetime-local` inputs and
an Apply action, with the active window echoed as text below.

Controlled: the caller owns `value` and receives the next window through
`onValueChange` — a preset click emits its token immediately, while the custom
inputs hold a working draft until Apply commits the normalized absolute range.

The drafts track the controlled value, re-seeded on a NEW absolute `value` (keyed
on `from`/`to`), so edits against an unchanged value are preserved but a genuinely
different value replaces an in-progress draft.

**Props**

| Prop | Type | Description |
| - | - | - |
| `aria-label?` | `string` | The control group's accessible name. |
| `disabled?` | `boolean` | — |
| `now?` | `() => Date` | The clock the absolute-range clamp reads. Defaults to the wall clock; a caller (or a test) injects a fixed instant to pin the "no future" boundary. |
| `onValueChange` | `(value: DateRangeValue) => void` | — |
| `presets?` | `readonly DateRangePreset[]` | The preset chips to offer. Defaults to DEFAULT\_DATE\_RANGE\_PRESETS. |
| `value` | `DateRangeValue` | — |

**Related:** [DateRangePickerProps](/reference/studio-sdk/components#daterangepickerprops)

## DateRangePickerProps

```ts theme={null}
interface DateRangePickerProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `aria-label?` | `string` | The control group's accessible name. |
| `disabled?` | `boolean` | — |
| `now?` | `() => Date` | The clock the absolute-range clamp reads. Defaults to the wall clock; a caller (or a test) injects a fixed instant to pin the "no future" boundary. |
| `onValueChange` | `(value: DateRangeValue) => void` | — |
| `presets?` | `readonly DateRangePreset[]` | The preset chips to offer. Defaults to DEFAULT\_DATE\_RANGE\_PRESETS. |
| `value` | `DateRangeValue` | — |

**Related:** [DateRangePreset](/reference/studio-sdk/components#daterangepreset), [DateRangeValue](/reference/studio-sdk/components#daterangevalue)

## DateRangePreset

```ts theme={null}
interface DateRangePreset
```

A relative preset: a `\d+[hdw]` token the backend resolves, plus its chip label.

**Properties**

| Property | Type | Description |
| - | - | - |
| `label` | `string` | — |
| `token` | `string` | — |

## DateRangeValue

```ts theme={null}
type DateRangeValue = { kind: "relative"; token: string } | { from: string; kind: "absolute"; to: string }
```

A named time window: either a relative token the backend resolves against its
own clock, or an absolute pair of ISO instants.

## Dialog

```ts theme={null}
function Dialog(props: DialogProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `children?` | `ReactNode` | — |
| `chromeless?` | `boolean` | Drop the forced visual `Title` and the `tai-stack` children wrapper, rendering `children` directly for a chrome-free content mode. The `title` is still required and still names the dialog — it renders visually-hidden — so the accessible name never depends on the visible chrome. |
| `contentClassName?` | `string` | A class merged onto `RadixDialog.Content` after the surface classes, for a host that must reach the content element itself — e.g. a plugin hanging its CSS-scoping root on the panel so its styles apply inside the Radix portal. |
| `defaultOpen?` | `boolean` | — |
| `description?` | `string` | — |
| `dismissable?` | `boolean` | When `false`, the light-dismiss gestures are disabled: Escape and a pointer press outside the panel no longer close it, so the only way out is an explicit action the `children` render (a Done/Cancel button calling `onOpenChange`). The focus trap, the scrim and every other Radix behaviour are unchanged. This is a generic mechanism — it knows nothing of what the dialog holds — for the one-time-reveal case where an accidental dismiss would lose content the server cannot reproduce. Defaults to `true`, the ordinary dismissable modal. This design-system panel renders no built-in close (X) affordance, so there is none to hide here; explicit close stays entirely with the caller's own buttons. |
| `fullscreen?` | `boolean` | Fill the viewport edge to edge instead of centring a fixed-size panel. The overlay, the focus trap and every other Radix behaviour are unchanged. |
| `onOpenChange?` | `(open: boolean) => void` | — |
| `open?` | `boolean` | — |
| `title` | `string` | — |
| `trigger?` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | A trigger element; when omitted, control the dialog via `open`/`onOpenChange`.  It is a single ELEMENT, not any node: Radix clones its props onto it, so a string throws. The type admits a FRAGMENT — `<></>` is a `ReactElement` — which would render openers carrying neither the `aria-haspopup`/`aria-expanded`/`aria-controls` wiring nor a click handler, so assertSlotElement rejects that one at runtime. |

**Related:** [DialogProps](/reference/studio-sdk/components#dialogprops)

## DialogProps

```ts theme={null}
interface DialogProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `children?` | `ReactNode` | — |
| `chromeless?` | `boolean` | Drop the forced visual `Title` and the `tai-stack` children wrapper, rendering `children` directly for a chrome-free content mode. The `title` is still required and still names the dialog — it renders visually-hidden — so the accessible name never depends on the visible chrome. |
| `contentClassName?` | `string` | A class merged onto `RadixDialog.Content` after the surface classes, for a host that must reach the content element itself — e.g. a plugin hanging its CSS-scoping root on the panel so its styles apply inside the Radix portal. |
| `defaultOpen?` | `boolean` | — |
| `description?` | `string` | — |
| `dismissable?` | `boolean` | When `false`, the light-dismiss gestures are disabled: Escape and a pointer press outside the panel no longer close it, so the only way out is an explicit action the `children` render (a Done/Cancel button calling `onOpenChange`). The focus trap, the scrim and every other Radix behaviour are unchanged. This is a generic mechanism — it knows nothing of what the dialog holds — for the one-time-reveal case where an accidental dismiss would lose content the server cannot reproduce. Defaults to `true`, the ordinary dismissable modal. This design-system panel renders no built-in close (X) affordance, so there is none to hide here; explicit close stays entirely with the caller's own buttons. |
| `fullscreen?` | `boolean` | Fill the viewport edge to edge instead of centring a fixed-size panel. The overlay, the focus trap and every other Radix behaviour are unchanged. |
| `onOpenChange?` | `(open: boolean) => void` | — |
| `open?` | `boolean` | — |
| `title` | `string` | — |
| `trigger?` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | A trigger element; when omitted, control the dialog via `open`/`onOpenChange`.  It is a single ELEMENT, not any node: Radix clones its props onto it, so a string throws. The type admits a FRAGMENT — `<></>` is a `ReactElement` — which would render openers carrying neither the `aria-haspopup`/`aria-expanded`/`aria-controls` wiring nor a click handler, so assertSlotElement rejects that one at runtime. |

## DirtyGuardBoundary

```ts theme={null}
function DirtyGuardBoundary(props: { children: ReactNode }): ReactNode
```

Boundary that guards navigation away from a region holding a dirty editor. Editors
inside it arm the guard through `useRegisterDirty`; while any is dirty a route
navigation (a route-token/plugin navigate, an `AppLink`, or a browser
back/forward) confirms through the shared discard dialog, and a full-page unload
raises the native prompt. Use this directly to guard a dirty editor that is a plain
page section (no tabs); `GuardedTabs` wraps this same boundary to additionally
guard tab switches.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `props` | `{ children: ReactNode }` | — | — |

## Drawer

```ts theme={null}
function Drawer(props: DrawerProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `children` | `ReactNode` | — |
| `defaultOpen?` | `boolean` | — |
| `onOpenChange?` | `(open: boolean) => void` | — |
| `open?` | `boolean` | — |
| `side?` | `"left" \| "right"` | — |
| `title` | `string` | The dialog's accessible name. |
| `trigger?` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | The opener. Radix labels it and returns focus to it when the drawer closes.  It is a single ELEMENT, not any node: Radix clones its props onto it, so a string throws. The type admits a FRAGMENT — `<></>` is a `ReactElement` — which would render openers carrying neither the `aria-haspopup`/`aria-expanded`/`aria-controls` wiring nor a click handler, so assertSlotElement rejects that one at runtime. |

**Related:** [DrawerProps](/reference/studio-sdk/components#drawerprops)

## DrawerProps

```ts theme={null}
interface DrawerProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `children` | `ReactNode` | — |
| `defaultOpen?` | `boolean` | — |
| `onOpenChange?` | `(open: boolean) => void` | — |
| `open?` | `boolean` | — |
| `side?` | `"left" \| "right"` | — |
| `title` | `string` | The dialog's accessible name. |
| `trigger?` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` | The opener. Radix labels it and returns focus to it when the drawer closes.  It is a single ELEMENT, not any node: Radix clones its props onto it, so a string throws. The type admits a FRAGMENT — `<></>` is a `ReactElement` — which would render openers carrying neither the `aria-haspopup`/`aria-expanded`/`aria-controls` wiring nor a click handler, so assertSlotElement rejects that one at runtime. |

## EditIcon

```ts theme={null}
const EditIcon: IconComponent
```

Edit: a pencil laid across the surface it writes on.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## EmptyState

```ts theme={null}
function EmptyState(props: EmptyStateProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `action?` | `ReactNode` | The guidance line's on-screen action — the control the description names. |
| `className?` | `string` | — |
| `description?` | `string` | — |
| `style?` | `CSSProperties` | — |
| `title` | `string` | — |

**Related:** [EmptyStateProps](/reference/studio-sdk/components#emptystateprops)

## EmptyStateProps

```ts theme={null}
interface EmptyStateProps extends SurfaceProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `action?` | `ReactNode` | The guidance line's on-screen action — the control the description names. |
| `className?` | `string` | — |
| `description?` | `string` | — |
| `style?` | `CSSProperties` | — |
| `title` | `string` | — |

## EntityCardGrid

```ts theme={null}
function EntityCardGrid(props: EntityCardGridProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `aria-label` | `string` | The grid's accessible name (e.g. "Tools"). Rendered as a `list` for AT. |
| `children` | `ReactNode` | — |

**Related:** [EntityCardGridProps](/reference/studio-sdk/components#entitycardgridprops)

## EntityCardGridProps

```ts theme={null}
interface EntityCardGridProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `aria-label` | `string` | The grid's accessible name (e.g. "Tools"). Rendered as a `list` for AT. |
| `children` | `ReactNode` | — |

## ErrorBoundary

```ts theme={null}
ErrorBoundary
```

## ErrorBoundaryProps

```ts theme={null}
interface ErrorBoundaryProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `children` | `ReactNode` | — |
| `label?` | `string` | Prefixed to the caught error message, naming the contained region. |
| `onError?` | `(error: unknown, info: ErrorInfo) => void` | Called with the caught error and React's component stack, for logging. |

## ErrorState

```ts theme={null}
function ErrorState(props: ErrorStateProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `className?` | `string` | — |
| `message` | `string` | — |
| `onRetry?` | `() => void` | — |
| `style?` | `CSSProperties` | — |

**Related:** [ErrorStateProps](/reference/studio-sdk/components#errorstateprops)

## ErrorStateProps

```ts theme={null}
interface ErrorStateProps extends SurfaceProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `className?` | `string` | — |
| `message` | `string` | — |
| `onRetry?` | `() => void` | — |
| `style?` | `CSSProperties` | — |

## ExecutionKeyPicker

```ts theme={null}
function ExecutionKeyPicker(props: ExecutionKeyPickerProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `error?` | `string` | The host form's required-field error, shown under the control. |
| `onValueChange` | `(value: string) => void` | — |
| `query` | `ExecutionKeyQuery` | The api-key list read the host feature owns and hands in. |
| `value` | `string` | — |

**Related:** [ExecutionKeyPickerProps](/reference/studio-sdk/components#executionkeypickerprops)

## ExecutionKeyPickerProps

```ts theme={null}
interface ExecutionKeyPickerProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `error?` | `string` | The host form's required-field error, shown under the control. |
| `onValueChange` | `(value: string) => void` | — |
| `query` | `ExecutionKeyQuery` | The api-key list read the host feature owns and hands in. |
| `value` | `string` | — |

**Related:** [ExecutionKeyQuery](/reference/studio-sdk/components#executionkeyquery)

## ExecutionKeyQuery

```ts theme={null}
interface ExecutionKeyQuery
```

The subset of the api-key list query this picker reads. A caller's TanStack
`UseQueryResult<TokensPayload>` satisfies it structurally, so the SDK names no
query library.

**Properties**

| Property | Type | Description |
| - | - | - |
| `data` | `({ condition: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; description: string; orphaned: boolean; policy_data: Record<string, unknown> \| null; principal: { display_name: string; kind: "human" \| "service"; user_id: string } \| null; scopes: string[] \| null; user_id: string })[] \| undefined` | — |
| `error` | `unknown` | — |
| `isError` | `boolean` | — |
| `isPending` | `boolean` | — |
| `isSuccess` | `boolean` | — |
| `refetch` | `() => void` | — |

## ExplorerColumn

```ts theme={null}
interface ExplorerColumn
```

One header cell of the table view. `renderRow` must emit exactly this many
`<TD>`s per item; folder rows span all of them.

**Properties**

| Property | Type | Description |
| - | - | - |
| `header` | `ReactNode` | — |
| `key` | `string` | — |
| `numeric?` | `boolean` | — |

## ExplorerEmptyState

```ts theme={null}
interface ExplorerEmptyState
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `action?` | `ReactNode` | — |
| `description?` | `string` | — |
| `title` | `string` | — |

## ExplorerEmptyStates

```ts theme={null}
interface ExplorerEmptyStates
```

The folder-aware empty-state ladder — every label caller-supplied.

**Properties**

| Property | Type | Description |
| - | - | - |
| `empty` | `ExplorerEmptyState` | No items and no folders exist at all. |
| `emptyFolder` | `ExplorerEmptyState` | The current folder holds nothing — no items, no subfolders — yet the  entity set is not globally empty. |
| `noMatch` | `ExplorerEmptyState` | The current folder has items but the active tag/search filter excludes  every one, and it has no subfolders to show. |

**Related:** [ExplorerEmptyState](/reference/studio-sdk/components#exploreremptystate)

## ExplorerSearch

```ts theme={null}
interface ExplorerSearch<T>
```

Controlled free-text search. `matches` owns the item shape and casing; it is
called only with a non-empty, already-trimmed query.

**Properties**

| Property | Type | Description |
| - | - | - |
| `label` | `string` | The input's accessible name. |
| `matches` | `(item: T, query: string) => boolean` | — |
| `onChange` | `(value: string) => void` | — |
| `placeholder?` | `string` | — |
| `value` | `string` | — |

## ExplorerTags

```ts theme={null}
interface ExplorerTags<T>
```

Enables the tag vocabulary, filter chips, and OR filter. Fully controlled.

**Properties**

| Property | Type | Description |
| - | - | - |
| `filterLabel` | `string` | The chip group's accessible name (e.g. "Filter tools by tag"). |
| `getTags` | `(item: T) => readonly string[]` | — |
| `maxVisibleTags?` | `number` | Collapse unselected chips beyond this count into a static "+N more"; unset  shows every chip. Selected chips always show. |
| `onChange` | `(selected: readonly string[]) => void` | — |
| `selected` | `readonly string[]` | — |
| `untaggedLabel` | `string` | The untagged pseudo-tag's visible label (e.g. "Untagged"). |

## ExplorerView

```ts theme={null}
function ExplorerView<T>(props: ExplorerViewProps<T>): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `columns` | `readonly ExplorerColumn[]` | — |
| `currentFolderId` | `string \| null` | — |
| `emptyStates` | `ExplorerEmptyStates` | — |
| `folders` | `readonly Folder[]` | — |
| `getFolderId` | `(item: T) => string \| null` | The folder an item is filed in (`null` = the root directory). |
| `getItemKey` | `(item: T) => string` | — |
| `items` | `readonly T[]` | — |
| `label` | `string` | The card grid's accessible name; the toggle's is "\<label> view". |
| `onNavigate` | `(folderId: string \| null) => void` | — |
| `onOpenItem?` | `(item: T) => void` | Open an item on a pointer click anywhere on its row/card — a convenience  ONLY. The accessible activation path stays the interactive element inside  the cell (the name link), so the row is never a focusable button; a click  originating on a nested control is left to that control. |
| `renderCard` | `(item: T) => ReactNode` | The item's `<Card>` — wrapped in a keyed `listitem` by the explorer. |
| `renderFolderActions?` | `(folder: Folder) => ReactNode` | Per-folder actions rendered on the folder's row/card (e.g. a kebab). |
| `renderRow` | `(item: T) => ReactNode` | The item's table cells (`<TD>`s) — wrapped in a keyed `<TR>` by the explorer. |
| `rootLabel` | `string` | — |
| `search?` | `ExplorerSearch<T>` | — |
| `tags?` | `ExplorerTags<T>` | — |
| `viewSurface` | `string` | Persist + drive the list/card toggle under this surface key. |

**Related:** [ExplorerViewProps](/reference/studio-sdk/components#explorerviewprops)

## ExplorerViewProps

```ts theme={null}
interface ExplorerViewProps<T>
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `columns` | `readonly ExplorerColumn[]` | — |
| `currentFolderId` | `string \| null` | — |
| `emptyStates` | `ExplorerEmptyStates` | — |
| `folders` | `readonly Folder[]` | — |
| `getFolderId` | `(item: T) => string \| null` | The folder an item is filed in (`null` = the root directory). |
| `getItemKey` | `(item: T) => string` | — |
| `items` | `readonly T[]` | — |
| `label` | `string` | The card grid's accessible name; the toggle's is "\<label> view". |
| `onNavigate` | `(folderId: string \| null) => void` | — |
| `onOpenItem?` | `(item: T) => void` | Open an item on a pointer click anywhere on its row/card — a convenience  ONLY. The accessible activation path stays the interactive element inside  the cell (the name link), so the row is never a focusable button; a click  originating on a nested control is left to that control. |
| `renderCard` | `(item: T) => ReactNode` | The item's `<Card>` — wrapped in a keyed `listitem` by the explorer. |
| `renderFolderActions?` | `(folder: Folder) => ReactNode` | Per-folder actions rendered on the folder's row/card (e.g. a kebab). |
| `renderRow` | `(item: T) => ReactNode` | The item's table cells (`<TD>`s) — wrapped in a keyed `<TR>` by the explorer. |
| `rootLabel` | `string` | — |
| `search?` | `ExplorerSearch<T>` | — |
| `tags?` | `ExplorerTags<T>` | — |
| `viewSurface` | `string` | Persist + drive the list/card toggle under this surface key. |

**Related:** [ExplorerColumn](/reference/studio-sdk/components#explorercolumn), [ExplorerEmptyStates](/reference/studio-sdk/components#exploreremptystates), [ExplorerSearch](/reference/studio-sdk/components#explorersearch), [ExplorerTags](/reference/studio-sdk/components#explorertags), [Folder](/reference/studio-sdk/components#folder)

## ExtensionComboBuilder

```ts theme={null}
function ExtensionComboBuilder(props: ExtensionComboBuilderProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `available` | `readonly ({ kind: string; multiple: boolean; name: string })[]` | The extension catalog the combos are drawn from (caller-fetched). |
| `availableReady?` | `boolean` | Whether the `available` catalog has finished loading. Default `true` (existing consumers keep today's behavior). While `false` the builder reports VALID and suppresses the unknown-name notes, so a stale-seeded combo does not flash invalid before the catalog resolves. |
| `disabled?` | `boolean` | — |
| `idPrefix?` | `string` | — |
| `onChange` | `(next: (string \| { config: z.ZodRecord<z.ZodString, z.ZodUnknown>; name: string })[][]) => void` | Fired with the next list of combos on every add/update/remove. |
| `onValidityChange?` | `(valid: boolean) => void` | Fired (effect-driven) on mount and whenever `value`, `available`, or `availableReady` changes with whether every combo's names are known. A caller blocks submit while this is `false`. The `onChange` payload shape is unchanged; this is a SECOND callback so the prop surface stays backward-compatible. |
| `value` | `readonly (string \| { config: z.ZodRecord<z.ZodString, z.ZodUnknown>; name: string })[][]` | The current list of combos, each an ordered list of extension elements. |

**Related:** [ExtensionComboBuilderProps](/reference/studio-sdk/components#extensioncombobuilderprops)

## ExtensionComboBuilderProps

```ts theme={null}
interface ExtensionComboBuilderProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `available` | `readonly ({ kind: string; multiple: boolean; name: string })[]` | The extension catalog the combos are drawn from (caller-fetched). |
| `availableReady?` | `boolean` | Whether the `available` catalog has finished loading. Default `true` (existing consumers keep today's behavior). While `false` the builder reports VALID and suppresses the unknown-name notes, so a stale-seeded combo does not flash invalid before the catalog resolves. |
| `disabled?` | `boolean` | — |
| `idPrefix?` | `string` | — |
| `onChange` | `(next: (string \| { config: z.ZodRecord<z.ZodString, z.ZodUnknown>; name: string })[][]) => void` | Fired with the next list of combos on every add/update/remove. |
| `onValidityChange?` | `(valid: boolean) => void` | Fired (effect-driven) on mount and whenever `value`, `available`, or `availableReady` changes with whether every combo's names are known. A caller blocks submit while this is `false`. The `onChange` payload shape is unchanged; this is a SECOND callback so the prop surface stays backward-compatible. |
| `value` | `readonly (string \| { config: z.ZodRecord<z.ZodString, z.ZodUnknown>; name: string })[][]` | The current list of combos, each an ordered list of extension elements. |

## ExtensionFamily

```ts theme={null}
interface ExtensionFamily
```

One base tool and every extension entry that branches from it.

**Properties**

| Property | Type | Description |
| - | - | - |
| `base` | `string` | The base tool name (the segment before the first underscore). |
| `members` | `readonly ({ kind: string; multiple: boolean; name: string })[]` | The family's entries, ordered by full name. |

## ExtensionKindGroup

```ts theme={null}
interface ExtensionKindGroup
```

One extension `kind` and every catalog entry of that kind.

**Properties**

| Property | Type | Description |
| - | - | - |
| `kind` | `string` | The serialized kind value (`wrapper` / `transformer` / `backend`). |
| `members` | `readonly ({ kind: string; multiple: boolean; name: string })[]` | The kind's entries, ordered by name. |
| `multiple` | `boolean` | Whether a combo may carry several extensions of this kind; `false` is single-select  in the picker. Served per kind by the catalog. |

## ExtensionPicker

```ts theme={null}
function ExtensionPicker(props: ExtensionPickerProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `available` | `readonly ({ kind: string; multiple: boolean; name: string })[]` | The extension catalog (`GET /api/extensions`) the checklist is drawn from. |
| `disabled?` | `boolean` | — |
| `idPrefix?` | `string` | — |
| `onChange` | `(names: string[]) => void` | Fired with the next ordered selection whenever a box toggles. |
| `value` | `readonly string[]` | The currently-selected extension names, in combo (stacking) order. |

**Related:** [ExtensionPickerProps](/reference/studio-sdk/components#extensionpickerprops)

## ExtensionPickerProps

```ts theme={null}
interface ExtensionPickerProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `available` | `readonly ({ kind: string; multiple: boolean; name: string })[]` | The extension catalog (`GET /api/extensions`) the checklist is drawn from. |
| `disabled?` | `boolean` | — |
| `idPrefix?` | `string` | — |
| `onChange` | `(names: string[]) => void` | Fired with the next ordered selection whenever a box toggles. |
| `value` | `readonly string[]` | The currently-selected extension names, in combo (stacking) order. |

## ExtensionsIcon

```ts theme={null}
const ExtensionsIcon: IconComponent
```

Extensions: a jigsaw piece — knob above, socket to the right.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## ExternalLinkButton

```ts theme={null}
function ExternalLinkButton(props: ExternalLinkButtonProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `children?` | `ReactNode` | — |
| `url` | `string` | — |

**Related:** [ExternalLinkButtonProps](/reference/studio-sdk/components#externallinkbuttonprops)

## ExternalLinkButtonProps

```ts theme={null}
interface ExternalLinkButtonProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `children?` | `ReactNode` | — |
| `url` | `string` | — |

## ExternalLinkIcon

```ts theme={null}
const ExternalLinkIcon: IconComponent
```

Opens in a new tab / leaves the app.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## EyeIcon

```ts theme={null}
const EyeIcon: IconComponent
```

Reveal a masked value.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## EyeOffIcon

```ts theme={null}
const EyeOffIcon: IconComponent
```

Mask a revealed value.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## Field

```ts theme={null}
function Field(props: FieldProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `children` | `ReactNode` | — |
| `className?` | `string` | APPENDED to `tai-field` rather than replacing it, so the field keeps its paint. |
| `description?` | `string` | — |
| `error?` | `string` | — |
| `group?` | `boolean` | Set when the wrapped control is a GROUP rather than one labelable element — a `RadioGroup`, a set of checkboxes, any `role="radiogroup"`/`role="group"` panel.  `<label for>` can only name a labelable element: pointed at a group it either dangles at an id no element carries or names an element the browser refuses to label, and it is inert either way. So a group Field wraps `children` in the group CONTAINER itself — a `<div role="group">` carrying `aria-labelledby` at the label and `aria-describedby` at the description and error — and the label becomes a `<span>`, because a `<label>` associated with nothing is a semantics lie.  IT ALSO CHANGES WHAT A CHILD READS FROM useFieldControl. The container is what carries the name and the description, so the group Field publishes NEITHER `id` NOR `aria-describedby` — both are `undefined`, and a control that spread them would take the group's own name and description for itself. `aria-invalid` still crosses: `role="group"` does not support it (ARIA 1.2), so the control is the only place an errored group can expose its invalid state.  Naming therefore happens BY CONSTRUCTION rather than by the call site remembering to read a hook. The cost is one extra container announcement where the child has a group role of its own; that is accepted deliberately, because the two failure directions are asymmetric — a redundant container is audible, an unnamed group is silent.  A group child left UNMARKED is a build failure, not a runtime surprise: `components/field-group.test.ts` ("Field group contract" → "marks every Field whose child does not claim its control id") scans every Field call site in the repository, and a child outside its list of control-id-claiming components — `RadioGroup` among them — reddens until the site passes `group`. |
| `hideLabel?` | `boolean` | Render the label for ASSISTIVE TECH ONLY — visually hidden, but still the control's accessible name through the very same `<label for>` (or, in a group, the same `aria-labelledby`). The label element stays in the DOM behind `tai-visually-hidden`, so nothing about the accessible name changes; only its paint is dropped. It is the standard idiom for a dense grid of otherwise identical fields, where each row needs a UNIQUE, addressable name (a voice-control user can only say a name that exists) but there is no room for a visible label on every row — the same trade `RadioGroup`'s `visuallyHiddenLabel` and `ViewToggle` make. The label text still governs WCAG 2.5.3 (Label in Name), so a caller passes the real per-row name as `label`, not a decoration. |
| `label` | `string` | — |
| `style?` | `CSSProperties` | — |

**Related:** [FieldProps](/reference/studio-sdk/components#fieldprops)

## FieldControlProps

```ts theme={null}
interface FieldControlProps
```

The a11y wiring a form control spreads onto its element.

**Properties**

| Property | Type | Description |
| - | - | - |
| `aria-describedby` | `string \| undefined` | — |
| `aria-invalid` | `true \| undefined` | — |
| `id` | `string \| undefined` | — |

## FieldProps

```ts theme={null}
interface FieldProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `children` | `ReactNode` | — |
| `className?` | `string` | APPENDED to `tai-field` rather than replacing it, so the field keeps its paint. |
| `description?` | `string` | — |
| `error?` | `string` | — |
| `group?` | `boolean` | Set when the wrapped control is a GROUP rather than one labelable element — a `RadioGroup`, a set of checkboxes, any `role="radiogroup"`/`role="group"` panel.  `<label for>` can only name a labelable element: pointed at a group it either dangles at an id no element carries or names an element the browser refuses to label, and it is inert either way. So a group Field wraps `children` in the group CONTAINER itself — a `<div role="group">` carrying `aria-labelledby` at the label and `aria-describedby` at the description and error — and the label becomes a `<span>`, because a `<label>` associated with nothing is a semantics lie.  IT ALSO CHANGES WHAT A CHILD READS FROM useFieldControl. The container is what carries the name and the description, so the group Field publishes NEITHER `id` NOR `aria-describedby` — both are `undefined`, and a control that spread them would take the group's own name and description for itself. `aria-invalid` still crosses: `role="group"` does not support it (ARIA 1.2), so the control is the only place an errored group can expose its invalid state.  Naming therefore happens BY CONSTRUCTION rather than by the call site remembering to read a hook. The cost is one extra container announcement where the child has a group role of its own; that is accepted deliberately, because the two failure directions are asymmetric — a redundant container is audible, an unnamed group is silent.  A group child left UNMARKED is a build failure, not a runtime surprise: `components/field-group.test.ts` ("Field group contract" → "marks every Field whose child does not claim its control id") scans every Field call site in the repository, and a child outside its list of control-id-claiming components — `RadioGroup` among them — reddens until the site passes `group`. |
| `hideLabel?` | `boolean` | Render the label for ASSISTIVE TECH ONLY — visually hidden, but still the control's accessible name through the very same `<label for>` (or, in a group, the same `aria-labelledby`). The label element stays in the DOM behind `tai-visually-hidden`, so nothing about the accessible name changes; only its paint is dropped. It is the standard idiom for a dense grid of otherwise identical fields, where each row needs a UNIQUE, addressable name (a voice-control user can only say a name that exists) but there is no room for a visible label on every row — the same trade `RadioGroup`'s `visuallyHiddenLabel` and `ViewToggle` make. The label text still governs WCAG 2.5.3 (Label in Name), so a caller passes the real per-row name as `label`, not a decoration. |
| `label` | `string` | — |
| `style?` | `CSSProperties` | — |

## FilterIcon

```ts theme={null}
const FilterIcon: IconComponent
```

A funnel.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## FleetReport

```ts theme={null}
function FleetReport(props: FleetReportProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `action?` | `"reload" \| "save" \| "deregister" \| "remove"` | Whose framing the copy takes: a saved config change (`'save'`), a dispatched reload (`'reload'`), a connector detach fan-out (`'deregister'`), or a live-registry tool removal (`'remove'`). All but `'save'` drop the "Change saved" framing; `'deregister'` and `'remove'` also point remediation back at re-running that same detach, since a reload would re-attach the detached server or tool. |
| `summary` | `FleetReportSummary \| null` | — |

**Related:** [FleetReportProps](/reference/studio-sdk/components#fleetreportprops)

## FleetReportProps

```ts theme={null}
interface FleetReportProps
```

Render a fleet broadcast's failure state and its workers awaiting a respawn. Returns
`null` for an absent report or a converged one with no worker awaiting a respawn
(nothing to warn about) so callers can always mount it unconditionally beside their
own success line.

**Properties**

| Property | Type | Description |
| - | - | - |
| `action?` | `"reload" \| "save" \| "deregister" \| "remove"` | Whose framing the copy takes: a saved config change (`'save'`), a dispatched reload (`'reload'`), a connector detach fan-out (`'deregister'`), or a live-registry tool removal (`'remove'`). All but `'save'` drop the "Change saved" framing; `'deregister'` and `'remove'` also point remediation back at re-running that same detach, since a reload would re-attach the detached server or tool. |
| `summary` | `FleetReportSummary \| null` | — |

## Folder

```ts theme={null}
interface Folder
```

A folder in the tree, in the SDK's camelCase UI shape (`parentId`, `null` = root).

**Properties**

| Property | Type | Description |
| - | - | - |
| `id` | `string` | — |
| `name` | `string` | — |
| `parentId` | `string \| null` | — |

## FolderBreadcrumb

```ts theme={null}
function FolderBreadcrumb(props: FolderBreadcrumbProps): ReactNode
```

The root → … → current path; each crumb navigates to that level.

**Props**

| Prop | Type | Description |
| - | - | - |
| `currentFolderId` | `string \| null` | — |
| `folders` | `readonly Folder[]` | — |
| `onNavigate` | `(folderId: string \| null) => void` | — |
| `rootLabel` | `string` | The root crumb's label (e.g. "All tools"). |

**Related:** [FolderBreadcrumbProps](/reference/studio-sdk/components#folderbreadcrumbprops)

## FolderBreadcrumbProps

```ts theme={null}
interface FolderBreadcrumbProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `currentFolderId` | `string \| null` | — |
| `folders` | `readonly Folder[]` | — |
| `onNavigate` | `(folderId: string \| null) => void` | — |
| `rootLabel` | `string` | The root crumb's label (e.g. "All tools"). |

**Related:** [Folder](/reference/studio-sdk/components#folder)

## FolderIcon

```ts theme={null}
const FolderIcon: IconComponent
```

Folder: a tabbed folder, for the tool-organization tree and breadcrumbs.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## FolderPicker

```ts theme={null}
function FolderPicker(props: FolderPickerProps): ReactNode
```

A folder chooser with inline new-folder creation, for the edit / move dialogs.

**Props**

| Prop | Type | Description |
| - | - | - |
| `disabled?` | `boolean` | — |
| `folders` | `readonly Folder[]` | — |
| `onChange` | `(folderId: string \| null) => void` | — |
| `onCreateFolder` | `(name: string, parentId: string \| null) => Promise<string>` | Create a folder under `parentId` (the current selection) and resolve with its id; the picker selects it. Rejection is the caller's to surface — the picker leaves the draft in place so the operator can retry. |
| `unfiledLabel` | `string` | The unfiled option's label (e.g. "No folder"). |
| `value` | `string \| null` | The chosen folder id, or `null` for unfiled. |

**Related:** [FolderPickerProps](/reference/studio-sdk/components#folderpickerprops)

## FolderPickerProps

```ts theme={null}
interface FolderPickerProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `disabled?` | `boolean` | — |
| `folders` | `readonly Folder[]` | — |
| `onChange` | `(folderId: string \| null) => void` | — |
| `onCreateFolder` | `(name: string, parentId: string \| null) => Promise<string>` | Create a folder under `parentId` (the current selection) and resolve with its id; the picker selects it. Rejection is the caller's to surface — the picker leaves the draft in place so the operator can retry. |
| `unfiledLabel` | `string` | The unfiled option's label (e.g. "No folder"). |
| `value` | `string \| null` | The chosen folder id, or `null` for unfiled. |

**Related:** [Folder](/reference/studio-sdk/components#folder)

## FolderRow

```ts theme={null}
function FolderRow(props: FolderRowProps): ReactNode
```

One subfolder in the current-directory explorer; opening it navigates inward.

**Props**

| Prop | Type | Description |
| - | - | - |
| `folder` | `Folder` | — |
| `onOpen` | `(folderId: string) => void` | — |

**Related:** [FolderRowProps](/reference/studio-sdk/components#folderrowprops)

## FolderRowProps

```ts theme={null}
interface FolderRowProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `folder` | `Folder` | — |
| `onOpen` | `(folderId: string) => void` | — |

**Related:** [Folder](/reference/studio-sdk/components#folder)

## FormDialog

```ts theme={null}
function FormDialog(props: FormDialogProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `cancelLabel?` | `string` | The Cancel button's label. |
| `children` | `ReactNode` | The form body — the caller's fields. |
| `description?` | `string` | — |
| `onClose` | `() => void` | Called on a close gesture (Cancel, Escape, overlay) and on a successful submit — at most once per dialog lifecycle. A close landing mid-submit wins: the later resolution does not fire a second `onClose`. |
| `onSubmit` | `() => void \| Promise<void>` | The action the form performs. A returned promise is awaited: the dialog closes only when it RESOLVES; a rejection (or a synchronous throw) keeps the dialog open and renders the failure loudly. A `void` return closes the dialog synchronously. |
| `pendingLabel` | `string` | The Spinner's accessible label while the action runs (e.g. `Creating`). |
| `submitDisabled?` | `boolean` | Blocks submission by click and by Enter while incomplete (a disabled default button is not an implicit-submission target). |
| `submitLabel` | `string` | The submit button's resting label (e.g. `Create scope`). |
| `submitVariant?` | `"primary" \| "danger"` | — |
| `title` | `string` | — |

**Related:** [FormDialogProps](/reference/studio-sdk/components#formdialogprops)

## FormDialogProps

```ts theme={null}
interface FormDialogProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `cancelLabel?` | `string` | The Cancel button's label. |
| `children` | `ReactNode` | The form body — the caller's fields. |
| `description?` | `string` | — |
| `onClose` | `() => void` | Called on a close gesture (Cancel, Escape, overlay) and on a successful submit — at most once per dialog lifecycle. A close landing mid-submit wins: the later resolution does not fire a second `onClose`. |
| `onSubmit` | `() => void \| Promise<void>` | The action the form performs. A returned promise is awaited: the dialog closes only when it RESOLVES; a rejection (or a synchronous throw) keeps the dialog open and renders the failure loudly. A `void` return closes the dialog synchronously. |
| `pendingLabel` | `string` | The Spinner's accessible label while the action runs (e.g. `Creating`). |
| `submitDisabled?` | `boolean` | Blocks submission by click and by Enter while incomplete (a disabled default button is not an implicit-submission target). |
| `submitLabel` | `string` | The submit button's resting label (e.g. `Create scope`). |
| `submitVariant?` | `"primary" \| "danger"` | — |
| `title` | `string` | — |

## GridIcon

```ts theme={null}
const GridIcon: IconComponent
```

Grid: a 2x2 tile array — the card-view half of the list/card toggle.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## GuardedTabs

```ts theme={null}
function GuardedTabs(props: { defaultValue?: string; items: readonly TabItem[] }): ReactNode
```

A drop-in replacement for `Tabs` that guards a switch away from a dirty
editor. Wraps the tabs in a `DirtyGuardBoundary`, so an editor rendered in
any panel can arm the guard through `useRegisterDirty`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `props` | `{ defaultValue?: string; items: readonly TabItem[] }` | — | — |

**Related:** [TabItem](/reference/studio-sdk/components#tabitem)

## HeadingLevel

```ts theme={null}
type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6
```

The heading levels ATX syntax can express, `#` through `######`.

## HooksIcon

```ts theme={null}
const HooksIcon: IconComponent
```

Hooks: a webhook fan-out — one source branching to two subscribers.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## IconComponent

```ts theme={null}
type IconComponent = (props: IconProps) => ReactElement
```

The shape every exported icon satisfies.

**Related:** [IconProps](/reference/studio-sdk/components#iconprops)

## IconProps

```ts theme={null}
type IconProps = SVGProps<SVGSVGElement>
```

Props of every icon: the full SVG surface, so `style`, events and ARIA pass
through. `className` is APPENDED to the `tai-icon` sizing class rather than
replacing it — the same merge every other design-system primitive does.

## InteractionsIcon

```ts theme={null}
const InteractionsIcon: IconComponent
```

Interactions: two overlapping speech bubbles — a conversation.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## JsonDiff

```ts theme={null}
function JsonDiff(props: JsonDiffProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `after` | `unknown` | — |
| `before` | `unknown` | — |

**Related:** [JsonDiffProps](/reference/studio-sdk/components#jsondiffprops)

## JsonDiffProps

```ts theme={null}
interface JsonDiffProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `after` | `unknown` | — |
| `before` | `unknown` | — |

## JsonDiffRow

```ts theme={null}
interface JsonDiffRow
```

One leaf difference between the two JSON values.

**Properties**

| Property | Type | Description |
| - | - | - |
| `after?` | `unknown` | The value on the RIGHT side — set for `added` and `changed` rows. |
| `before?` | `unknown` | The value on the LEFT side — set for `removed` and `changed` rows. |
| `kind` | `"added" \| "removed" \| "changed"` | — |
| `path` | `string` | The dotted path to the differing key, e.g. `fixed_kwargs.city` (`''` = root). |

## JsonTree

```ts theme={null}
function JsonTree(props: JsonTreeProps): ReactElement
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `data` | `unknown` | — |
| `defaultExpanded?` | `boolean` | Opts the whole tree out of the depth-guarded default: `true` expands every node (up to the depth cap), `false` collapses to the root. Omitted, the tree opens through AUTO\_EXPAND\_DEPTH and collapses everything below. |
| `label?` | `string` | The region's accessible name, applied only while the pane actually scrolls. |
| `openPaths?` | `readonly readonly string[][]` | Paths whose containers open beside the baseline, at any depth: each path lists the keys from the root (an array item by its index, as a string), and the root, every container along it and the one it ends at open. The reader's own toggle still wins, and collapse-all closes them like every other node. |

**Related:** [JsonTreeProps](/reference/studio-sdk/components#jsontreeprops)

## JsonTreeProps

```ts theme={null}
interface JsonTreeProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `data` | `unknown` | — |
| `defaultExpanded?` | `boolean` | Opts the whole tree out of the depth-guarded default: `true` expands every node (up to the depth cap), `false` collapses to the root. Omitted, the tree opens through AUTO\_EXPAND\_DEPTH and collapses everything below. |
| `label?` | `string` | The region's accessible name, applied only while the pane actually scrolls. |
| `openPaths?` | `readonly readonly string[][]` | Paths whose containers open beside the baseline, at any depth: each path lists the keys from the root (an array item by its index, as a string), and the root, every container along it and the one it ends at open. The reader's own toggle still wins, and collapse-all closes them like every other node. |

## LinkButtonProps

```ts theme={null}
interface LinkButtonProps extends ButtonVariantProps, AnchorHTMLAttributes<HTMLAnchorElement>
```

The LINK form of `Button`: an `href`, so it carries anchor attributes and no
button ones.

`target` and `rel` are inherited from `AnchorHTMLAttributes` and are settable,
but on the EXTERNAL branch they are not the caller's to choose: an absolute
http(s) URL always renders `target="_blank"` with
`rel="noopener noreferrer external"`, whatever the caller passed. On the
in-app branch `target` is the caller's and `rel` is pinned only when they ask
for `_blank`.

It declares NO `ref`, and that is a REFUSAL rather than an omission: a blocked
href renders a `NeutralizedLink` span and no anchor at all, so a
`Ref<HTMLAnchorElement>` would be filled on two of the three renderings and
left null on the third — a ref that silently does nothing for exactly the
input the check exists to catch. A caller that needs the element wraps the
button.

**Properties**

| Property | Type | Description |
| - | - | - |
| `href` | `string` | — |
| `variant?` | `ButtonVariant` | — |

**Related:** [ButtonVariant](/reference/studio-sdk/components#buttonvariant)

## ManifestIcon

```ts theme={null}
const ManifestIcon: IconComponent
```

Manifest: a document with a folded corner and its entries.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## Markdown

```ts theme={null}
function Markdown(props: MarkdownProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `className?` | `string` | Appended to `tai-prose` so a caller can position the block without losing its paint. |
| `markdown` | `string` | The markdown source. Rendered as an escaped-by-construction React tree. |

**Related:** [MarkdownProps](/reference/studio-sdk/components#markdownprops)

## MarkdownBlock

```ts theme={null}
type MarkdownBlock = { level: HeadingLevel; text: string; type: "heading" } | { text: string; type: "paragraph" } | { code: string; language: string | undefined; type: "code" } | { items: readonly string[]; ordered: boolean; start?: number; type: "list" } | { children: readonly MarkdownBlock[]; type: "blockquote" } | { type: "thematicBreak" }
```

A parsed block. Inline markup inside `text` is resolved at render time.

**Related:** [HeadingLevel](/reference/studio-sdk/components#headinglevel)

## MarkdownProps

```ts theme={null}
interface MarkdownProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `className?` | `string` | Appended to `tai-prose` so a caller can position the block without losing its paint. |
| `markdown` | `string` | The markdown source. Rendered as an escaped-by-construction React tree. |

## MarketplaceIcon

```ts theme={null}
const MarketplaceIcon: IconComponent
```

Marketplace: a shopping bag.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## MediaDocument

```ts theme={null}
function MediaDocument(props: MediaDocumentProps): ReactNode
```

One document: a labelled download affordance. The served route sends
`Content-Disposition: attachment` for documents, so the anchor `download`-hints and
opens in a new tab; `rel="noreferrer"` stops the Studio URL leaking to the media
host. A url that fails `isRenderableMediaSrc` is the caller's notice, never a
live href.

**Props**

| Prop | Type | Description |
| - | - | - |
| `label` | `string` | The download label: the item's filename or caption, or the caller's default. |
| `renderNotice` | `(url: string) => ReactNode` | Render the notice shown when the url fails the src gate. |
| `url` | `string` | — |

**Related:** [MediaDocumentProps](/reference/studio-sdk/components#mediadocumentprops)

## MediaDocumentProps

```ts theme={null}
interface MediaDocumentProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `label` | `string` | The download label: the item's filename or caption, or the caller's default. |
| `renderNotice` | `(url: string) => ReactNode` | Render the notice shown when the url fails the src gate. |
| `url` | `string` | — |

## MediaImage

```ts theme={null}
function MediaImage(props: MediaImageProps): ReactNode
```

One served/remote image. Its own component (not an inline `.map` body) because the
load-failure flag is per-image `useState`, which the rules of hooks forbid inside a
`.map` callback. `referrerPolicy="no-referrer"` is REQUIRED: it stops the Studio URL
(which can encode the interaction/operator context) from leaking to the image host
on a remote-image load. `altFallback` supplies the `alt` when the item has no caption;
a caller overrides it for its own content and can supply `renderNotice` to render the
blocked/failed states in its own presentation.

**Props**

| Prop | Type | Description |
| - | - | - |
| `allowDataImage?` | `boolean` | Opt in to inline `data:image/*` sources (default OFF). Set ONLY by a sink that stores media raw; a `data:` of any other type stays blocked. See isRenderableMediaSrc. |
| `altFallback?` | `string` | The `alt` text when the item carries no caption. |
| `caption?` | `string` | — |
| `renderNotice?` | `(state: "failed" \| "blocked", url: string) => ReactNode` | Render the notice shown when no image is displayed: `state` is `'blocked'` when the url fails the src gate and `'failed'` when an admitted url fails to LOAD, and `url` is that url. When omitted, the SDK's own danger-badge notice (with the url) is rendered. |
| `url` | `string` | — |

**Related:** [MediaImageProps](/reference/studio-sdk/components#mediaimageprops)

## MediaImageProps

```ts theme={null}
interface MediaImageProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `allowDataImage?` | `boolean` | Opt in to inline `data:image/*` sources (default OFF). Set ONLY by a sink that stores media raw; a `data:` of any other type stays blocked. See isRenderableMediaSrc. |
| `altFallback?` | `string` | The `alt` text when the item carries no caption. |
| `caption?` | `string` | — |
| `renderNotice?` | `(state: "failed" \| "blocked", url: string) => ReactNode` | Render the notice shown when no image is displayed: `state` is `'blocked'` when the url fails the src gate and `'failed'` when an admitted url fails to LOAD, and `url` is that url. When omitted, the SDK's own danger-badge notice (with the url) is rendered. |
| `url` | `string` | — |

## MediaPlayer

```ts theme={null}
function MediaPlayer(props: MediaPlayerProps): ReactNode
```

A native `<audio>`/`<video controls>` player. `referrerPolicy` is not a valid
attribute on `<audio>`/`<video>`, so a remote load has no per-element referrer
control; the player therefore admits ONLY the platform's own served-media reference
(`isServedMediaUrl`: same-origin, leaking no page URL to a media host), and any
other url, a bare `https:` one included, is the caller's notice. The load-failure
flag keys on the url that failed so a new url at the same position gets a fresh load.

**Props**

| Prop | Type | Description |
| - | - | - |
| `kind` | `"audio" \| "video"` | — |
| `label` | `string` | The player's accessible label. |
| `renderNotice` | `(state: "failed" \| "blocked", url: string) => ReactNode` | Render the notice shown when no player is displayed: `state` is `'blocked'` when the url is not a served reference and `'failed'` when it fails to LOAD. |
| `url` | `string` | — |

**Related:** [MediaPlayerProps](/reference/studio-sdk/components#mediaplayerprops)

## MediaPlayerProps

```ts theme={null}
interface MediaPlayerProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `kind` | `"audio" \| "video"` | — |
| `label` | `string` | The player's accessible label. |
| `renderNotice` | `(state: "failed" \| "blocked", url: string) => ReactNode` | Render the notice shown when no player is displayed: `state` is `'blocked'` when the url is not a served reference and `'failed'` when it fails to LOAD. |
| `url` | `string` | — |

## MembersIcon

```ts theme={null}
const MembersIcon: IconComponent
```

Members: two people — a front figure with a second shouldered behind it.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## MenuIcon

```ts theme={null}
const MenuIcon: IconComponent
```

The three-bar menu / drawer toggle.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## MinusIcon

```ts theme={null}
const MinusIcon: IconComponent
```

A bare dash, for a partial selection — the tick's mixed-state counterpart.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## MonitorIcon

```ts theme={null}
const MonitorIcon: IconComponent
```

Follow the operating system.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## MoonIcon

```ts theme={null}
const MoonIcon: IconComponent
```

Dark theme.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## NAV\_ICONS

```ts theme={null}
const NAV_ICONS: Readonly<Record<Exclude<RouteToken, "login">, IconComponent>>
```

The canonical mark for every navigable route token. `login` is excluded: it is
not a destination the navigation surfaces list. Keyed by the token type, so
adding a route to `RouteToken` fails the build here until it gets a mark.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent), [RouteToken](/reference/studio-sdk/navigation#routetoken)

## NotificationsIcon

```ts theme={null}
const NotificationsIcon: IconComponent
```

Notifications: a bell with its clapper.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## NumberInput

```ts theme={null}
function NumberInput(props: NumberInputProps): Element
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `props` | `NumberInputProps` | — | — |

**Related:** [NumberInputProps](/reference/studio-sdk/components#numberinputprops)

## NumberInputProps

```ts theme={null}
type NumberInputProps = Omit<InputHTMLAttributes<HTMLInputElement>, "type"> & ControlRefProps<HTMLInputElement>
```

## NumericColumnProps

```ts theme={null}
interface NumericColumnProps
```

Right-align a column of digits on tabular figures.

**Properties**

| Property | Type | Description |
| - | - | - |
| `numeric?` | `boolean` | — |

## OpenTargetOptions

```ts theme={null}
interface OpenTargetOptions
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `ignoreWithin?` | `string` | Extra selector(s) that also count as "nested interactive" for THIS surface,  merged with the built-in set. Use it for a marked non-`button`/`a` subtree  that owns its own clicks (e.g. an expandable preview keyed by a data  attribute). Standard CSS selector syntax, comma-separated. |
| `keyboard?` | `boolean` | Make the entry itself keyboard-operable: a `tabIndex: 0` focus stop with  Enter/Space activation. Leave off when a nested interactive element already  carries the accessible path (see the keyboard note above) — adding it there  would create a duplicate tab stop. |
| `onOpen` | `() => void \| undefined` | Open the entry. `undefined` disables the affordance entirely — the helper  returns empty props so the element stays inert (no cursor, no handlers),  which lets a caller wire the whole thing behind an optional prop. |

## OpenTargetProps

```ts theme={null}
interface OpenTargetProps
```

The React attributes `openTargetProps` yields — spread onto the entry
element (`<TR>`, card `<div>`). Every field is optional so the disabled case
is the empty object.

**Properties**

| Property | Type | Description |
| - | - | - |
| `onClick?` | `(event: MouseEvent<HTMLElement>) => void` | — |
| `onKeyDown?` | `(event: KeyboardEvent<HTMLElement>) => void` | — |
| `style?` | `{ cursor: "pointer" }` | — |
| `tabIndex?` | `number` | — |

## OverflowAxis

```ts theme={null}
type OverflowAxis = "horizontal" | "vertical"
```

The axis a scroll region is measured on. A prose table or a code line scrolls
SIDEWAYS (`horizontal`, the default); a bounded, capped-height list scrolls
DOWN (`vertical`). Both wear the same conditional region attributes — only the
dimension read to decide whether they overflow differs.

## OverflowRegionAttributes

```ts theme={null}
interface OverflowRegionAttributes
```

The attribute set a scrolling box wears; every value is absent while it fits.

**Properties**

| Property | Type | Description |
| - | - | - |
| `aria-label?` | `string` | — |
| `ref` | `RefCallback<HTMLElement>` | Attach to the scrolling element; it is what the measurement follows. |
| `role?` | `"region"` | — |
| `tabIndex?` | `0` | — |

## OverlayDetails

```ts theme={null}
interface OverlayDetails
```

The two overlay fields this control edits.

**Properties**

| Property | Type | Description |
| - | - | - |
| `displayName` | `string` | The raw display-name draft (unblank-normalized only at write time). |
| `tags` | `readonly string[]` | — |

## OverlayDetailsFields

```ts theme={null}
function OverlayDetailsFields(props: OverlayDetailsFieldsProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `disabled?` | `boolean` | — |
| `namePlaceholder?` | `string` | The tool's real name, shown as the display-name input's placeholder so an empty override reads as "falls back to \<name>". |
| `nativeTags?` | `readonly string[]` | Read-only plugin-native tags, rendered as distinct chips. Present only in the edit surfaces that want native and overlay tags shown apart. |
| `onChange` | `(next: OverlayDetails) => void` | — |
| `value` | `OverlayDetails` | — |

**Related:** [OverlayDetailsFieldsProps](/reference/studio-sdk/components#overlaydetailsfieldsprops)

## OverlayDetailsFieldsProps

```ts theme={null}
interface OverlayDetailsFieldsProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `disabled?` | `boolean` | — |
| `namePlaceholder?` | `string` | The tool's real name, shown as the display-name input's placeholder so an empty override reads as "falls back to \<name>". |
| `nativeTags?` | `readonly string[]` | Read-only plugin-native tags, rendered as distinct chips. Present only in the edit surfaces that want native and overlay tags shown apart. |
| `onChange` | `(next: OverlayDetails) => void` | — |
| `value` | `OverlayDetails` | — |

**Related:** [OverlayDetails](/reference/studio-sdk/components#overlaydetails)

## Page

```ts theme={null}
function Page(props: PageLayoutProps): ReactElement
```

The screen wrapper: the max-width, the gutters, and the vertical rhythm.

**Props**

| Prop | Type | Description |
| - | - | - |
| `children` | `ReactNode` | — |
| `className?` | `string` | — |
| `ref?` | `Ref<HTMLDivElement>` | A consumer ref for the wrapper element itself. |
| `style?` | `CSSProperties` | — |

**Related:** [PageLayoutProps](/reference/studio-sdk/components#pagelayoutprops)

## PageFillProvider

```ts theme={null}
function PageFillProvider(props: { children: ReactNode }): ReactNode
```

Wraps the shell's routed region: holds the count of pages asking for fill mode
and publishes both the registrar (for `useFillViewport`) and the active
flag (for `usePageFillActive`). Renders no DOM of its own.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `props` | `{ children: ReactNode }` | — | — |

## PageHeader

```ts theme={null}
function PageHeader(props: PageHeaderProps): ReactElement
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `actions?` | `ReactNode` | — |
| `description?` | `string` | — |
| `eyebrow?` | `string` | The screen's existing nav-section label, rendered ABOVE the h1 — never inside it. |
| `id?` | `string` | An id for the `<h1>`, not for the `<header>` root. The heading is the element a caller has a reason to address — an `aria-labelledby` pointing at it names the region from the screen's own title — and it is the other way to reach it as a focus target. |
| `title` | `string` | The screen's title. It is the `<h1>`'s accessible name, VERBATIM. |
| `titleRef?` | `Ref<HTMLHeadingElement>` | A consumer ref for the `<h1>`. Published so a caller that wants to move focus to the new screen's title — after a route change, say — has the element without querying for it; the heading is focusable for that reason. |

**Related:** [PageHeaderProps](/reference/studio-sdk/components#pageheaderprops)

## PageHeaderProps

```ts theme={null}
interface PageHeaderProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `actions?` | `ReactNode` | — |
| `description?` | `string` | — |
| `eyebrow?` | `string` | The screen's existing nav-section label, rendered ABOVE the h1 — never inside it. |
| `id?` | `string` | An id for the `<h1>`, not for the `<header>` root. The heading is the element a caller has a reason to address — an `aria-labelledby` pointing at it names the region from the screen's own title — and it is the other way to reach it as a focus target. |
| `title` | `string` | The screen's title. It is the `<h1>`'s accessible name, VERBATIM. |
| `titleRef?` | `Ref<HTMLHeadingElement>` | A consumer ref for the `<h1>`. Published so a caller that wants to move focus to the new screen's title — after a route change, say — has the element without querying for it; the heading is focusable for that reason. |

## PageLayoutProps

```ts theme={null}
interface PageLayoutProps extends LayoutElementProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `children` | `ReactNode` | — |
| `className?` | `string` | — |
| `ref?` | `Ref<HTMLDivElement>` | A consumer ref for the wrapper element itself. |
| `style?` | `CSSProperties` | — |

## PendingIcon

```ts theme={null}
const PendingIcon: IconComponent
```

Pending / running / queued — a clock hand inside a dashed ring.

The dash period has to TILE the circumference or the ring closes on a seam.
At r = 9 the circumference is 2π·9 = 56.5487. A 3.2/3.2 array (period 6.4)
fits 8.84 times, so the ring shut with a 2.15 gap instead of 3.2 — and with
the inherited round linecap eating 1.6 at each end that seam rendered \~0.37 px
wide at 16 px, reading as joined while every other gap read as a gap. Eight
whole periods divide it exactly: 56.5487 / 8 = 7.0686, halved for the dash and
the gap = 3.5343 each, giving 16 even segments and no seam.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## PluginIcon

```ts theme={null}
const PluginIcon: IconComponent
```

Plugin: a puzzle piece — the host's provenance mark for plugin-contributed nav.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## PlusIcon

```ts theme={null}
const PlusIcon: IconComponent
```

Add / insert: the dash crossed by an upright, for an append or attach affordance.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## PresetsIcon

```ts theme={null}
const PresetsIcon: IconComponent
```

Presets: three sliders, each with its knob at a different stop.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## ProgressBar

```ts theme={null}
function ProgressBar(props: ProgressBarProps): ReactNode
```

Render a progress bar. With a positive `total`, `value/total` fills the track
and the percentage is announced via `aria-valuenow`; without one, the bar is
indeterminate (no `aria-valuenow`, per ARIA).

**Props**

| Prop | Type | Description |
| - | - | - |
| `message?` | `string` | Optional human-readable status shown alongside the bar. |
| `total?` | `number` | Upper bound. When absent or non-positive the bar is INDETERMINATE. |
| `value?` | `number` | Current progress. Clamped to `[0, total]` when `total` is known. |

**Related:** [ProgressBarProps](/reference/studio-sdk/components#progressbarprops)

## ProgressBarProps

```ts theme={null}
interface ProgressBarProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `message?` | `string` | Optional human-readable status shown alongside the bar. |
| `total?` | `number` | Upper bound. When absent or non-positive the bar is INDETERMINATE. |
| `value?` | `number` | Current progress. Clamped to `[0, total]` when `total` is known. |

## ProseScrollLabels

```ts theme={null}
interface ProseScrollLabels
```

The fallback name per instrumented surface, when no heading precedes it.

**Properties**

| Property | Type | Description |
| - | - | - |
| `pre?` | `string` | — |
| `table?` | `string` | — |

## RadioGroup

```ts theme={null}
function RadioGroup(props: RadioGroupProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `aria-label?` | `string` | Accessible group name when `label` supplies none. `label` wins where both are given — it names the group from visible text, and emitting both would leave this string computed by nothing. |
| `defaultValue?` | `string` | — |
| `disabled?` | `boolean` | — |
| `label?` | `string` | Visible group label, rendered above the options and wired as the group's name. |
| `name?` | `string` | — |
| `onValueChange?` | `(value: string) => void` | — |
| `options` | `readonly RadioOption[]` | — |
| `orientation?` | `"horizontal" \| "vertical"` | Layout, and — when given — the arrow-key axis. Omitted, the options stack and BOTH axes move between them, which is what Radix does with no orientation and what every caller that never passed one already had. Pass a value only to pin the axis as well. |
| `value?` | `string` | — |
| `variant?` | `"list" \| "segmented"` | `list` is a stack of labelled radios; `segmented` is a compact segment strip. |

**Related:** [RadioGroupProps](/reference/studio-sdk/components#radiogroupprops)

## RadioGroupProps

```ts theme={null}
interface RadioGroupProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `aria-label?` | `string` | Accessible group name when `label` supplies none. `label` wins where both are given — it names the group from visible text, and emitting both would leave this string computed by nothing. |
| `defaultValue?` | `string` | — |
| `disabled?` | `boolean` | — |
| `label?` | `string` | Visible group label, rendered above the options and wired as the group's name. |
| `name?` | `string` | — |
| `onValueChange?` | `(value: string) => void` | — |
| `options` | `readonly RadioOption[]` | — |
| `orientation?` | `"horizontal" \| "vertical"` | Layout, and — when given — the arrow-key axis. Omitted, the options stack and BOTH axes move between them, which is what Radix does with no orientation and what every caller that never passed one already had. Pass a value only to pin the axis as well. |
| `value?` | `string` | — |
| `variant?` | `"list" \| "segmented"` | `list` is a stack of labelled radios; `segmented` is a compact segment strip. |

**Related:** [RadioOption](/reference/studio-sdk/components#radiooption)

## RadioOption

```ts theme={null}
interface RadioOption
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `disabled?` | `boolean` | — |
| `icon?` | `ReactNode` | Mark rendered alongside the label. Decorative — the label carries the name. |
| `label` | `string` | — |
| `value` | `string` | — |
| `visuallyHiddenLabel?` | `boolean` | Render the label for screen readers only; it stays the option's accessible name. |

## RevealInput

```ts theme={null}
function RevealInput(props: RevealInputProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `aria-label?` | `string` | Accessible name for the inner input when no visual `label` is rendered. |
| `disabled?` | `boolean` | — |
| `idPrefix?` | `string` | — |
| `label?` | `string` | — |
| `onChange?` | `(value: string) => void` | — |
| `placeholder?` | `string` | — |
| `readOnly?` | `boolean` | — |
| `value` | `string` | — |

**Related:** [RevealInputProps](/reference/studio-sdk/components#revealinputprops)

## RevealInputProps

```ts theme={null}
interface RevealInputProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `aria-label?` | `string` | Accessible name for the inner input when no visual `label` is rendered. |
| `disabled?` | `boolean` | — |
| `idPrefix?` | `string` | — |
| `label?` | `string` | — |
| `onChange?` | `(value: string) => void` | — |
| `placeholder?` | `string` | — |
| `readOnly?` | `boolean` | — |
| `value` | `string` | — |

## SUBJECT\_INCOMPLETE\_MESSAGE

```ts theme={null}
const SUBJECT_INCOMPLETE_MESSAGE: "A subject needs a target, a kind, and a key."
```

The message a partially-filled subject is refused with (all three fields or none).

## SchedulingIcon

```ts theme={null}
const SchedulingIcon: IconComponent
```

Scheduling: a calendar grid with its binding posts.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## ScrollRegion

```ts theme={null}
function ScrollRegion(props: ScrollRegionProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `axis?` | `OverflowAxis` | The dimension overflow is measured on. `horizontal` (the default) fits a pane that scrolls sideways; `vertical` fits a bounded, capped-height box that scrolls down. The caller styles the box's own overflow to match. |
| `children` | `ReactNode` | — |
| `className?` | `string` | — |
| `data-testid?` | `string` | The one arbitrary attribute this component forwards. The measured attributes — `tabindex`, `role` and `aria-label` — are the component's own and appear and disappear with the overflow, so a general attribute spread would let a caller set them statically and defeat the measurement. A test hook cannot, which is why it is the exception rather than the first of a set. |
| `label` | `string` | The region's accessible name, applied only while it actually scrolls. |
| `ref?` | `Ref<HTMLDivElement>` | A consumer ref for the scrolling `div` itself. |
| `style?` | `CSSProperties` | — |

**Related:** [ScrollRegionProps](/reference/studio-sdk/components#scrollregionprops)

## ScrollRegionProps

```ts theme={null}
interface ScrollRegionProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `axis?` | `OverflowAxis` | The dimension overflow is measured on. `horizontal` (the default) fits a pane that scrolls sideways; `vertical` fits a bounded, capped-height box that scrolls down. The caller styles the box's own overflow to match. |
| `children` | `ReactNode` | — |
| `className?` | `string` | — |
| `data-testid?` | `string` | The one arbitrary attribute this component forwards. The measured attributes — `tabindex`, `role` and `aria-label` — are the component's own and appear and disappear with the overflow, so a general attribute spread would let a caller set them statically and defeat the measurement. A test hook cannot, which is why it is the exception rather than the first of a set. |
| `label` | `string` | The region's accessible name, applied only while it actually scrolls. |
| `ref?` | `Ref<HTMLDivElement>` | A consumer ref for the scrolling `div` itself. |
| `style?` | `CSSProperties` | — |

**Related:** [OverflowAxis](/reference/studio-sdk/components#overflowaxis)

## SearchIcon

```ts theme={null}
const SearchIcon: IconComponent
```

A magnifier.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## Select

```ts theme={null}
function Select(props: SelectArgs): Element
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `props` | `SelectArgs` | — | — |

## SelectGroup

```ts theme={null}
interface SelectGroup
```

A labelled cluster of options (e.g. tools grouped by tag).

**Properties**

| Property | Type | Description |
| - | - | - |
| `label` | `string` | — |
| `options` | `readonly SelectOption[]` | — |

**Related:** [SelectOption](/reference/studio-sdk/components#selectoption)

## SelectGroupsProps

```ts theme={null}
interface SelectGroupsProps extends SelectSharedProps
```

The GROUPED listbox: labelled clusters, each carrying its own options.

**Properties**

| Property | Type | Description |
| - | - | - |
| `aria-describedby?` | `string` | IDREFs of elements that describe the trigger. An enclosing `Field` owns entries in the same list (its description and error), so the two are concatenated, caller's first, exactly as the text inputs do. |
| `aria-label?` | `string` | Accessible name for the trigger when it is not wired to an enclosing `Field`. A `Field` wins where both are given — it names the trigger from visible text, and `aria-label` would override that native label and leave the visible text out of the accessible name (WCAG 2.5.3). |
| `defaultValue?` | `string` | — |
| `disabled?` | `boolean` | — |
| `groups` | `readonly SelectGroup[]` | — |
| `name?` | `string` | — |
| `onValueChange?` | `(value: string) => void` | — |
| `placeholder?` | `string` | — |
| `value?` | `string` | — |

**Related:** [SelectGroup](/reference/studio-sdk/components#selectgroup)

## SelectOption

```ts theme={null}
interface SelectOption
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `disabled?` | `boolean` | — |
| `label` | `string` | — |
| `value` | `string` | — |

## SelectProps

```ts theme={null}
interface SelectProps extends SelectSharedProps
```

The FLAT listbox: one ungrouped run of options.

**Properties**

| Property | Type | Description |
| - | - | - |
| `aria-describedby?` | `string` | IDREFs of elements that describe the trigger. An enclosing `Field` owns entries in the same list (its description and error), so the two are concatenated, caller's first, exactly as the text inputs do. |
| `aria-label?` | `string` | Accessible name for the trigger when it is not wired to an enclosing `Field`. A `Field` wins where both are given — it names the trigger from visible text, and `aria-label` would override that native label and leave the visible text out of the accessible name (WCAG 2.5.3). |
| `defaultValue?` | `string` | — |
| `disabled?` | `boolean` | — |
| `name?` | `string` | — |
| `onValueChange?` | `(value: string) => void` | — |
| `options` | `readonly SelectOption[]` | — |
| `placeholder?` | `string` | — |
| `value?` | `string` | — |

**Related:** [SelectOption](/reference/studio-sdk/components#selectoption)

## ServedEndpointsIcon

```ts theme={null}
const ServedEndpointsIcon: IconComponent
```

Served endpoints: a broadcast node radiating to the tools it serves.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## ServedMediaGrammar

```ts theme={null}
type ServedMediaGrammar = unknown
```

The served-media grammar the contract publishes, read from the injected client
(`useApi().constants`): the served route prefix and the stored-media id pattern. Media is
stored by reference and served from the API origin at `MEDIA_ROUTE_PREFIX + <id>`; a record
carries it as a RELATIVE url of exactly that shape, resolved to the API base at render time
(`resolveMediaSrc`), not assumed same-origin as the SPA page.

## SettingsIcon

```ts theme={null}
const SettingsIcon: IconComponent
```

Settings: an eight-tooth cog around its bore.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## SignOutIcon

```ts theme={null}
const SignOutIcon: IconComponent
```

Sign out: a door with an outbound arrow.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## Skeleton

```ts theme={null}
function Skeleton(props: SkeletonProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `className?` | `string` | — |
| `height?` | `string \| number` | — |
| `style?` | `CSSProperties` | — |
| `width?` | `string \| number` | — |

**Related:** [SkeletonProps](/reference/studio-sdk/components#skeletonprops)

## SkeletonProps

```ts theme={null}
interface SkeletonProps extends SurfaceProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `className?` | `string` | — |
| `height?` | `string \| number` | — |
| `style?` | `CSSProperties` | — |
| `width?` | `string \| number` | — |

## SortAscIcon

```ts theme={null}
const SortAscIcon: IconComponent
```

Ascending sort: an up arrow beside narrow-to-wide rows.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## SortDescIcon

```ts theme={null}
const SortDescIcon: IconComponent
```

Descending sort: a down arrow beside wide-to-narrow rows.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## Spinner

```ts theme={null}
function Spinner(props: SpinnerProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `className?` | `string` | — |
| `label?` | `string` | — |
| `style?` | `CSSProperties` | — |

**Related:** [SpinnerProps](/reference/studio-sdk/components#spinnerprops)

## SpinnerProps

```ts theme={null}
interface SpinnerProps extends SurfaceProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `className?` | `string` | — |
| `label?` | `string` | — |
| `style?` | `CSSProperties` | — |

## Stack

```ts theme={null}
function Stack(props: StackProps): ReactElement
```

A vertical flex column on the spacing scale.

**Props**

| Prop | Type | Description |
| - | - | - |
| `children` | `ReactNode` | — |
| `className?` | `string` | — |
| `gap?` | `2 \| 3 \| 4 \| 6` | The gap step; 4 is the default and needs no modifier class. |
| `ref?` | `Ref<HTMLDivElement>` | A consumer ref for the wrapper element itself. |
| `style?` | `CSSProperties` | — |

**Related:** [StackProps](/reference/studio-sdk/components#stackprops)

## StackProps

```ts theme={null}
interface StackProps extends LayoutElementProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `children` | `ReactNode` | — |
| `className?` | `string` | — |
| `gap?` | `2 \| 3 \| 4 \| 6` | The gap step; 4 is the default and needs no modifier class. |
| `ref?` | `Ref<HTMLDivElement>` | A consumer ref for the wrapper element itself. |
| `style?` | `CSSProperties` | — |

## StorageIcon

```ts theme={null}
const StorageIcon: IconComponent
```

Storage: a database cylinder with two shelves.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## SubjectSection

```ts theme={null}
function SubjectSection(props: SubjectSectionProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `caption` | `string` | The block's descriptive caption, shown under the expanded header. |
| `error` | `string \| null` | — |
| `kind` | `string` | — |
| `onKeyChange` | `(value: string) => void` | — |
| `onKindChange` | `(value: string) => void` | — |
| `onTargetChange` | `(value: string) => void` | — |
| `onToggle` | `() => void` | — |
| `open` | `boolean` | — |
| `subjectKey` | `string` | — |
| `subjectKeyDescription` | `string` | The Subject key field's helper description. |
| `target` | `string` | — |
| `targetOptions` | `readonly SubjectTargetOption[]` | — |
| `targetPlaceholder` | `string` | The target select's empty-choice placeholder. |

**Related:** [SubjectSectionProps](/reference/studio-sdk/components#subjectsectionprops)

## SubjectSectionProps

```ts theme={null}
interface SubjectSectionProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `caption` | `string` | The block's descriptive caption, shown under the expanded header. |
| `error` | `string \| null` | — |
| `kind` | `string` | — |
| `onKeyChange` | `(value: string) => void` | — |
| `onKindChange` | `(value: string) => void` | — |
| `onTargetChange` | `(value: string) => void` | — |
| `onToggle` | `() => void` | — |
| `open` | `boolean` | — |
| `subjectKey` | `string` | — |
| `subjectKeyDescription` | `string` | The Subject key field's helper description. |
| `target` | `string` | — |
| `targetOptions` | `readonly SubjectTargetOption[]` | — |
| `targetPlaceholder` | `string` | The target select's empty-choice placeholder. |

**Related:** [SubjectTargetOption](/reference/studio-sdk/components#subjecttargetoption)

## SubjectTargetOption

```ts theme={null}
interface SubjectTargetOption
```

One conversation-target option: `target_kind:target_name` value, `kind · name` label.

**Properties**

| Property | Type | Description |
| - | - | - |
| `label` | `string` | — |
| `value` | `string` | — |

## SunIcon

```ts theme={null}
const SunIcon: IconComponent
```

Light theme.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## SystemIcon

```ts theme={null}
const SystemIcon: IconComponent
```

System: a processor die with its pins.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## TBody

```ts theme={null}
function TBody(props: TableSectionProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `children?` | `ReactNode` | — |
| `ref?` | `Ref<HTMLTableSectionElement>` | A consumer ref for the section element itself. |

**Related:** [TableSectionProps](/reference/studio-sdk/components#tablesectionprops)

## TD

```ts theme={null}
function TD(props: TDProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `children?` | `ReactNode` | — |
| `numeric?` | `boolean` | — |
| `ref?` | `Ref<HTMLTableCellElement>` | A consumer ref for the `<td>` itself. |

**Related:** [TDProps](/reference/studio-sdk/components#tdprops)

## TDProps

```ts theme={null}
interface TDProps extends TdHTMLAttributes<HTMLTableCellElement>, NumericColumnProps
```

Right-align a column of digits on tabular figures.

**Properties**

| Property | Type | Description |
| - | - | - |
| `children?` | `ReactNode` | — |
| `numeric?` | `boolean` | — |
| `ref?` | `Ref<HTMLTableCellElement>` | A consumer ref for the `<td>` itself. |

**Related:** [NumericColumnProps](/reference/studio-sdk/components#numericcolumnprops)

## TH

```ts theme={null}
function TH(props: THProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `children?` | `ReactNode` | — |
| `numeric?` | `boolean` | — |
| `ref?` | `Ref<HTMLTableCellElement>` | A consumer ref for the `<th>` itself. |

**Related:** [THProps](/reference/studio-sdk/components#thprops)

## THProps

```ts theme={null}
interface THProps extends ThHTMLAttributes<HTMLTableCellElement>, NumericColumnProps
```

A header cell. `scope` defaults to `col` because that is what a `<th>` in the
header row IS, and without it nothing associates the cell with the column
below it: a screen reader announcing a data cell has no header to name it.
A row header — the leading cell of a body row — passes `scope="row"`.

**Properties**

| Property | Type | Description |
| - | - | - |
| `children?` | `ReactNode` | — |
| `numeric?` | `boolean` | — |
| `ref?` | `Ref<HTMLTableCellElement>` | A consumer ref for the `<th>` itself. |

**Related:** [NumericColumnProps](/reference/studio-sdk/components#numericcolumnprops)

## THead

```ts theme={null}
function THead(props: TableSectionProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `children?` | `ReactNode` | — |
| `ref?` | `Ref<HTMLTableSectionElement>` | A consumer ref for the section element itself. |

**Related:** [TableSectionProps](/reference/studio-sdk/components#tablesectionprops)

## TOKEN\_NAMES

```ts theme={null}
const TOKEN_NAMES: readonly ["--tai-color-bg", "--tai-color-surface", "--tai-color-surface-raised", "--tai-color-surface-disabled", "--tai-color-code-bg", "--tai-color-border", "--tai-color-border-strong", "--tai-color-control-border", "--tai-color-border-disabled", "--tai-color-text", "--tai-color-heading", "--tai-color-text-muted", "--tai-color-text-disabled", "--tai-color-placeholder", "--tai-color-decor", "--tai-color-accent", "--tai-color-accent-hover", "--tai-color-accent-on-tint", "--tai-color-on-accent", "--tai-color-accent-tint", "--tai-color-ok-text", "--tai-color-err-text", "--tai-color-warn-text", "--tai-color-ok-fill", "--tai-color-err-fill", "--tai-color-warn-fill", "--tai-color-ok-tint", "--tai-color-err-tint", "--tai-color-warn-tint", "--tai-color-on-fill", "--tai-color-focus-ring", "--tai-color-scrim", "--tai-color-prose-link", "--tai-color-prose-link-hover", "--tai-color-syntax-key", "--tai-color-syntax-string", "--tai-color-syntax-number", "--tai-color-syntax-bool", "--tai-color-primary", "--tai-color-primary-text", "--tai-color-danger", "--tai-color-danger-text", "--tai-color-danger-hover", "--tai-color-danger-surface", "--tai-color-success", "--tai-color-warning", "--tai-space-1", "--tai-space-2", "--tai-space-3", "--tai-space-4", "--tai-space-5", "--tai-space-6", "--tai-space-8", "--tai-radius-sm", "--tai-radius-code", "--tai-radius-md", "--tai-radius-tile", "--tai-radius-lg", "--tai-radius-overlay", "--tai-radius-full", "--tai-font-sans", "--tai-font-mono", "--tai-text-display", "--tai-text-xl", "--tai-text-section", "--tai-text-lg", "--tai-text-md", "--tai-text-sm", "--tai-text-code", "--tai-text-xs", "--tai-control-height", "--tai-control-height-coarse", "--tai-motion-fast", "--tai-motion-base", "--tai-shadow-lift-color", "--tai-shadow-overlay-color", "--tai-shadow-lift", "--tai-shadow-overlay", "--tai-shadow-sm", "--tai-shadow-md", "--tai-z-sticky", "--tai-z-dropdown", "--tai-z-overlay", "--tai-z-dialog", "--tai-z-popover", "--tai-z-tooltip"]
```

The documented CSS-variable token names — the Studio-plugin styling API. A
snapshot test pins this list so the contract can't drift silently. The
SDK compatibility version bumps if any of these are renamed/removed; the list
grows additively.

The `--tai-dark-*` half of each themed pair is deliberately NOT here. Those
names are the theming mechanism's own storage — the two blocks in `tokens.css`
that apply the dark theme are the only readers, and the scanner test holds
them to that. A plugin styles against the name WITHOUT the `dark` segment and
gets whichever half the viewer's theme resolves to.

## TR

```ts theme={null}
function TR(props: TableRowProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `children?` | `ReactNode` | — |
| `ref?` | `Ref<HTMLTableRowElement>` | A consumer ref for the `<tr>` itself. |

**Related:** [TableRowProps](/reference/studio-sdk/components#tablerowprops)

## TabItem

```ts theme={null}
interface TabItem
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `content` | `ReactNode` | — |
| `disabled?` | `boolean` | — |
| `label` | `string` | — |
| `value` | `string` | — |

## Table

```ts theme={null}
function Table(props: TableProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `children?` | `ReactNode` | — |
| `ref?` | `Ref<HTMLTableElement>` | A consumer ref for the `<table>` itself. |

**Related:** [TableProps](/reference/studio-sdk/components#tableprops)

## TableProps

```ts theme={null}
interface TableProps extends HTMLAttributes<HTMLTableElement>
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `children?` | `ReactNode` | — |
| `ref?` | `Ref<HTMLTableElement>` | A consumer ref for the `<table>` itself. |

## TableRowProps

```ts theme={null}
interface TableRowProps extends HTMLAttributes<HTMLTableRowElement>
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `children?` | `ReactNode` | — |
| `ref?` | `Ref<HTMLTableRowElement>` | A consumer ref for the `<tr>` itself. |

## TableSectionProps

```ts theme={null}
interface TableSectionProps extends HTMLAttributes<HTMLTableSectionElement>
```

`<thead>` and `<tbody>` take the same surface: the native one.

**Properties**

| Property | Type | Description |
| - | - | - |
| `children?` | `ReactNode` | — |
| `ref?` | `Ref<HTMLTableSectionElement>` | A consumer ref for the section element itself. |

## Tabs

```ts theme={null}
function Tabs(props: TabsProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `activationMode?` | `"manual" \| "automatic"` | `'manual'` commits on Enter/Space/click only — arrows just move focus. |
| `defaultValue?` | `string` | — |
| `items` | `readonly TabItem[]` | — |
| `onValueChange?` | `(value: string) => void` | — |
| `value?` | `string` | — |

**Related:** [TabsProps](/reference/studio-sdk/components#tabsprops)

## TabsProps

```ts theme={null}
interface TabsProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `activationMode?` | `"manual" \| "automatic"` | `'manual'` commits on Enter/Space/click only — arrows just move focus. |
| `defaultValue?` | `string` | — |
| `items` | `readonly TabItem[]` | — |
| `onValueChange?` | `(value: string) => void` | — |
| `value?` | `string` | — |

**Related:** [TabItem](/reference/studio-sdk/components#tabitem)

## TagChips

```ts theme={null}
function TagChips(props: TagChipsProps): ReactNode
```

Read-only chips for a list of tags. Renders nothing when there are none.

**Props**

| Prop | Type | Description |
| - | - | - |
| `tags` | `readonly string[]` | — |

**Related:** [TagChipsProps](/reference/studio-sdk/components#tagchipsprops)

## TagChipsProps

```ts theme={null}
interface TagChipsProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `tags` | `readonly string[]` | — |

## TagVocabularyEntry

```ts theme={null}
interface TagVocabularyEntry
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `count` | `number` | — |
| `label` | `string` | — |
| `token` | `string` | — |

## TagsInput

```ts theme={null}
function TagsInput(props: TagsInputProps): ReactNode
```

Controlled tag editor. The caller owns the `value` list; `onChange` receives the
next list on every add/remove. A blank or duplicate entry is ignored (never a
silent duplicate chip). Enter or comma commits the draft chip.

The draft input is a NATIVE-ATTRIBUTE PASS-THROUGH (the family `inputs.tsx`
documents): inside a `Field` it renders the SDK's `TextInput`, which spreads
`useFieldControl()` and so claims the Field's control id, taking the Field's
visible label as its name; mounted OUTSIDE a `Field` it is named by a caller
`aria-label`, which the editor forwards to that same input. Without one a bare
editor is unnamed — the published component owns the naming route rather than
assuming a `Field` is always present. When a `Field` DOES name it, a caller
`aria-label` still has to CONTAIN that visible label (WCAG 2.5.3, Label in
Name); `components/field-group.test.ts` enforces that at every call site.

**Props**

| Prop | Type | Description |
| - | - | - |
| `aria-label?` | `string` | The draft input's accessible name when no enclosing `Field` supplies one. Forwarded to the input as a native attribute — see the docblock below. |
| `disabled?` | `boolean` | — |
| `itemNoun?` | `string` | The noun for the placeholder + the Add/Remove control names ("tag" by default). Set it (e.g. "badge") so a second editor on the same surface reads and, above all, has DISTINCT accessible control names — two "Add tag" buttons would be ambiguous to a name-based query and a screen reader alike. |
| `onChange` | `(next: string[]) => void` | — |
| `value` | `readonly string[]` | — |

**Related:** [TagsInputProps](/reference/studio-sdk/components#tagsinputprops)

## TagsInputProps

```ts theme={null}
interface TagsInputProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `aria-label?` | `string` | The draft input's accessible name when no enclosing `Field` supplies one. Forwarded to the input as a native attribute — see the docblock below. |
| `disabled?` | `boolean` | — |
| `itemNoun?` | `string` | The noun for the placeholder + the Add/Remove control names ("tag" by default). Set it (e.g. "badge") so a second editor on the same surface reads and, above all, has DISTINCT accessible control names — two "Add tag" buttons would be ambiguous to a name-based query and a screen reader alike. |
| `onChange` | `(next: string[]) => void` | — |
| `value` | `readonly string[]` | — |

## TemplatedTextField

```ts theme={null}
function TemplatedTextField(props: TemplatedTextFieldProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `description?` | `string` | Group-level helper shown under the label, above the source toggle. |
| `disabled?` | `boolean` | — |
| `error?` | `string` | A field-level error surfaced beneath the control. |
| `label` | `string` | The field's accessible name, shown on the active editor. |
| `onChange` | `(value: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null) => void` | — |
| `onTemplatesRetry?` | `() => void` | — |
| `placeholder?` | `string` | Placeholder for the default textarea editor (ignored when `renderInline` is given). |
| `renderInline?` | `(props: TemplatedTextInlineProps) => ReactNode` | Supply a custom inline-content editor (jq, rich text); defaults to a textarea. |
| `required?` | `boolean` | When true the field must carry a source: clearing the inline text or leaving the template unchosen emits an EMPTY source (not `null`), so the schema guard and the field error refuse the save rather than silently dropping the field. |
| `resolveError?` | `string` | The verbatim server message when the stored `id` no longer resolves. |
| `storageAbsent?` | `boolean` | Storage is registered ABSENT (`GET /api/storage` → `present: false`) — a fully supported configuration in which stored templates can be neither browsed nor resolved. The stored source is therefore not offered: an inline or empty value shows the inline editor alone (no toggle, no catalog); a value that already carries an `id` is shown READ-ONLY with its kwargs and a note that stored templates are unavailable here — the authored value is never converted to inline, dropped, or blanked. |
| `storagePresenceLoading?` | `boolean` | Storage presence is not yet known. A placeholder stands in for the source region so the toggle is not shown and then removed once presence resolves. |
| `templates?` | `readonly TemplatedTextTemplateOption[]` | The stored templates the id picker offers. |
| `templatesError?` | `string` | The template list fetch failed — surfaced with a retry. |
| `templatesLoading?` | `boolean` | The template list fetch is in flight. |
| `value` | `{ content?: string; id?: string; kwargs?: Record<string, unknown> } \| null` | — |

**Related:** [TemplatedTextFieldProps](/reference/studio-sdk/components#templatedtextfieldprops)

## TemplatedTextFieldProps

```ts theme={null}
interface TemplatedTextFieldProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `description?` | `string` | Group-level helper shown under the label, above the source toggle. |
| `disabled?` | `boolean` | — |
| `error?` | `string` | A field-level error surfaced beneath the control. |
| `label` | `string` | The field's accessible name, shown on the active editor. |
| `onChange` | `(value: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null) => void` | — |
| `onTemplatesRetry?` | `() => void` | — |
| `placeholder?` | `string` | Placeholder for the default textarea editor (ignored when `renderInline` is given). |
| `renderInline?` | `(props: TemplatedTextInlineProps) => ReactNode` | Supply a custom inline-content editor (jq, rich text); defaults to a textarea. |
| `required?` | `boolean` | When true the field must carry a source: clearing the inline text or leaving the template unchosen emits an EMPTY source (not `null`), so the schema guard and the field error refuse the save rather than silently dropping the field. |
| `resolveError?` | `string` | The verbatim server message when the stored `id` no longer resolves. |
| `storageAbsent?` | `boolean` | Storage is registered ABSENT (`GET /api/storage` → `present: false`) — a fully supported configuration in which stored templates can be neither browsed nor resolved. The stored source is therefore not offered: an inline or empty value shows the inline editor alone (no toggle, no catalog); a value that already carries an `id` is shown READ-ONLY with its kwargs and a note that stored templates are unavailable here — the authored value is never converted to inline, dropped, or blanked. |
| `storagePresenceLoading?` | `boolean` | Storage presence is not yet known. A placeholder stands in for the source region so the toggle is not shown and then removed once presence resolves. |
| `templates?` | `readonly TemplatedTextTemplateOption[]` | The stored templates the id picker offers. |
| `templatesError?` | `string` | The template list fetch failed — surfaced with a retry. |
| `templatesLoading?` | `boolean` | The template list fetch is in flight. |
| `value` | `{ content?: string; id?: string; kwargs?: Record<string, unknown> } \| null` | — |

**Related:** [TemplatedTextInlineProps](/reference/studio-sdk/components#templatedtextinlineprops), [TemplatedTextTemplateOption](/reference/studio-sdk/components#templatedtexttemplateoption)

## TemplatedTextInlineProps

```ts theme={null}
interface TemplatedTextInlineProps
```

The props `renderInline` receives to draw the inline-content editor.

**Properties**

| Property | Type | Description |
| - | - | - |
| `error?` | `string` | — |
| `hideLabel` | `boolean` | The field renders its own group header (label + description) above the source toggle, so the inline editor's OWN visible label is redundant: an editor honours this by rendering that label visually hidden while keeping it as its accessible name (its `<label for>` association stays intact). Always `true` — the control is always grouped — so an editor that draws its own label must respect it. |
| `label` | `string` | — |
| `onChange` | `(value: string) => void` | — |
| `value` | `string` | — |

## TemplatedTextTemplateOption

```ts theme={null}
interface TemplatedTextTemplateOption
```

One stored template the id picker offers.

**Properties**

| Property | Type | Description |
| - | - | - |
| `id` | `string` | — |
| `label?` | `string` | The label shown for the id; defaults to the id itself. |

## TemplatesIcon

```ts theme={null}
const TemplatesIcon: IconComponent
```

Templates: a stack of two sheets, the front one offset.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## TextInput

```ts theme={null}
function TextInput(props: TextInputProps): Element
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `props` | `TextInputProps` | — | — |

**Related:** [TextInputProps](/reference/studio-sdk/components#textinputprops)

## TextInputProps

```ts theme={null}
type TextInputProps = InputHTMLAttributes<HTMLInputElement> & ControlRefProps<HTMLInputElement>
```

## Textarea

```ts theme={null}
function Textarea(props: TextareaProps): Element
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `props` | `TextareaProps` | — | — |

**Related:** [TextareaProps](/reference/studio-sdk/components#textareaprops)

## TextareaProps

```ts theme={null}
type TextareaProps = TextareaHTMLAttributes<HTMLTextAreaElement> & ControlRefProps<HTMLTextAreaElement>
```

## TokenName

```ts theme={null}
type TokenName = typeof TOKEN_NAMES[number]
```

**Related:** [TOKEN\_NAMES](/reference/studio-sdk/components#token_names)

## ToolPicker

```ts theme={null}
function ToolPicker(props: ToolPickerProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `agentToolNames?` | `ReadonlySet<string>` | Tool names that are agent run tools; their option labels are suffixed " (agent)". |
| `aria-label?` | `string` | Accessible name for the tool listbox when `label` renders none and no enclosing `Field` names it. `label` wins where both are given: it names the control from visible text, and the `Select` drops a caller name it would otherwise override. |
| `badgesByTool?` | `Readonly<Record<string, readonly string[]>>` | Per-tool DECLARED capability badges (native ∪ overlay). When present, the selected tool's badges render as read-only chips beneath the select — purely informational, never affecting which options show or how they group. |
| `disabled?` | `boolean` | — |
| `displayNames?` | `Readonly<Record<string, string>>` | Human display names keyed by raw tool name (from the tool-meta overlay). A mapped option's label reads `Display Name (raw_name)`; an unmapped name — or a mapping equal to the raw name — reads the bare raw name. The value `onChange` emits stays the raw name in every case. |
| `excludeNames?` | `readonly string[]` | Names removed from the options (the server remains the authority). |
| `idPrefix?` | `string` | — |
| `label?` | `string` | — |
| `onChange` | `(toolName: string) => void` | — |
| `placeholder?` | `string` | — |
| `tagsByTool?` | `Readonly<Record<string, readonly string[]>>` | Per-tool native tags; when present, options are grouped and a tag filter shows. |
| `toolNames` | `readonly string[]` | — |
| `value` | `string \| null` | — |

**Related:** [ToolPickerProps](/reference/studio-sdk/components#toolpickerprops)

## ToolPickerProps

```ts theme={null}
interface ToolPickerProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `agentToolNames?` | `ReadonlySet<string>` | Tool names that are agent run tools; their option labels are suffixed " (agent)". |
| `aria-label?` | `string` | Accessible name for the tool listbox when `label` renders none and no enclosing `Field` names it. `label` wins where both are given: it names the control from visible text, and the `Select` drops a caller name it would otherwise override. |
| `badgesByTool?` | `Readonly<Record<string, readonly string[]>>` | Per-tool DECLARED capability badges (native ∪ overlay). When present, the selected tool's badges render as read-only chips beneath the select — purely informational, never affecting which options show or how they group. |
| `disabled?` | `boolean` | — |
| `displayNames?` | `Readonly<Record<string, string>>` | Human display names keyed by raw tool name (from the tool-meta overlay). A mapped option's label reads `Display Name (raw_name)`; an unmapped name — or a mapping equal to the raw name — reads the bare raw name. The value `onChange` emits stays the raw name in every case. |
| `excludeNames?` | `readonly string[]` | Names removed from the options (the server remains the authority). |
| `idPrefix?` | `string` | — |
| `label?` | `string` | — |
| `onChange` | `(toolName: string) => void` | — |
| `placeholder?` | `string` | — |
| `tagsByTool?` | `Readonly<Record<string, readonly string[]>>` | Per-tool native tags; when present, options are grouped and a tag filter shows. |
| `toolNames` | `readonly string[]` | — |
| `value` | `string \| null` | — |

## ToolsIcon

```ts theme={null}
const ToolsIcon: IconComponent
```

Tools: an open-ended spanner over its handle.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## Tooltip

```ts theme={null}
function Tooltip(props: TooltipProps): Element
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `children` | `ReactElement` | The element the bubble describes and hangs off.  It is a single ELEMENT, not any node: Radix clones its props onto it, so a string throws. The type admits a FRAGMENT — `<></>` is a `ReactElement` — which would render children carrying none of the hover/focus wiring nor the `aria-describedby` back to the bubble, so assertSlotElement rejects that one at runtime. |
| `content` | `ReactNode` | — |
| `delayDuration?` | `number` | — |

**Related:** [TooltipProps](/reference/studio-sdk/components#tooltipprops)

## TooltipProps

```ts theme={null}
interface TooltipProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `children` | `ReactElement` | The element the bubble describes and hangs off.  It is a single ELEMENT, not any node: Radix clones its props onto it, so a string throws. The type admits a FRAGMENT — `<></>` is a `ReactElement` — which would render children carrying none of the hover/focus wiring nor the `aria-describedby` back to the bubble, so assertSlotElement rejects that one at runtime. |
| `content` | `ReactNode` | — |
| `delayDuration?` | `number` | — |

## UNTAGGED\_TOKEN

```ts theme={null}
const UNTAGGED_TOKEN: "__untagged__"
```

Reserved filter token for items carrying NO tag; namespaced so it never
collides with a real tag.

## UnplugIcon

```ts theme={null}
const UnplugIcon: IconComponent
```

Detach / unmount: a plug pulled from its socket, the two prongs above the gap.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## VersionHistoryEntry

```ts theme={null}
interface VersionHistoryEntry
```

One version row — the kind-agnostic shape every consumer projects into.

**Properties**

| Property | Type | Description |
| - | - | - |
| `body` | `unknown` | — |
| `created_at` | `string` | — |
| `is_current` | `boolean` | — |
| `tags?` | `readonly string[]` | The version's generic label list, surfaced as a Tags column when present. |
| `version` | `number` | — |

## VersionHistoryPanel

```ts theme={null}
function VersionHistoryPanel(props: VersionHistoryPanelProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `onEditTags?` | `(version: number, tags: string[]) => Promise<void>` | Replace one version's tag annotation. When provided, a per-row "Edit tags" action opens a dialog seeded from the row's tags and SAVE calls this with the NEW list; the panel awaits the returned promise with internal pending/error state. Omitted ⇒ no edit affordance (tags stay read-only). |
| `onRollback` | `(version: number) => void` | Roll the active pointer to `version`. The consumer owns the mutation. |
| `onView?` | `(version: number) => void` | Fired when a version is selected for viewing (optional). |
| `readOnly?` | `boolean` | A read-only history view: the version list and each version's body stay visible (history is a read surface), but EVERY mutating action is hidden — the per-row Rollback and, where `onEditTags` is supplied, Edit tags. Defaults to interactive. |
| `rollbackConfirmDescription?` | `string` | Extra consequence copy appended to the rollback confirm dialog's description (announced to assistive tech via the dialog's `aria-describedby`). Consumers whose rollback has an immediate live effect (e.g. re-pointing access-control enforcement) pass a sentence stating so; omitted when there is nothing extra. |
| `rollbackError?` | `string` | A loud rollback failure message to surface in the confirm dialog. |
| `rollbackPending?` | `boolean` | The consumer's rollback mutation is in flight. |
| `versions` | `readonly VersionHistoryEntry[]` | — |

**Related:** [VersionHistoryPanelProps](/reference/studio-sdk/components#versionhistorypanelprops)

## VersionHistoryPanelProps

```ts theme={null}
interface VersionHistoryPanelProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `onEditTags?` | `(version: number, tags: string[]) => Promise<void>` | Replace one version's tag annotation. When provided, a per-row "Edit tags" action opens a dialog seeded from the row's tags and SAVE calls this with the NEW list; the panel awaits the returned promise with internal pending/error state. Omitted ⇒ no edit affordance (tags stay read-only). |
| `onRollback` | `(version: number) => void` | Roll the active pointer to `version`. The consumer owns the mutation. |
| `onView?` | `(version: number) => void` | Fired when a version is selected for viewing (optional). |
| `readOnly?` | `boolean` | A read-only history view: the version list and each version's body stay visible (history is a read surface), but EVERY mutating action is hidden — the per-row Rollback and, where `onEditTags` is supplied, Edit tags. Defaults to interactive. |
| `rollbackConfirmDescription?` | `string` | Extra consequence copy appended to the rollback confirm dialog's description (announced to assistive tech via the dialog's `aria-describedby`). Consumers whose rollback has an immediate live effect (e.g. re-pointing access-control enforcement) pass a sentence stating so; omitted when there is nothing extra. |
| `rollbackError?` | `string` | A loud rollback failure message to surface in the confirm dialog. |
| `rollbackPending?` | `boolean` | The consumer's rollback mutation is in flight. |
| `versions` | `readonly VersionHistoryEntry[]` | — |

**Related:** [VersionHistoryEntry](/reference/studio-sdk/components#versionhistoryentry)

## ViewMode

```ts theme={null}
type ViewMode = "list" | "cards"
```

The two entity-screen layouts.

## ViewToggle

```ts theme={null}
function ViewToggle(props: ViewToggleProps): ReactNode
```

The icon-only segmented switch. Controlled: pair it with `useViewMode`.

**Props**

| Prop | Type | Description |
| - | - | - |
| `aria-label` | `string` | The control's accessible group name (e.g. "Tools view"). |
| `disabled?` | `boolean` | — |
| `onValueChange` | `(mode: ViewMode) => void` | — |
| `value` | `ViewMode` | — |

**Related:** [ViewToggleProps](/reference/studio-sdk/components#viewtoggleprops)

## ViewToggleProps

```ts theme={null}
interface ViewToggleProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `aria-label` | `string` | The control's accessible group name (e.g. "Tools view"). |
| `disabled?` | `boolean` | — |
| `onValueChange` | `(mode: ViewMode) => void` | — |
| `value` | `ViewMode` | — |

**Related:** [ViewMode](/reference/studio-sdk/components#viewmode)

## XCircleIcon

```ts theme={null}
const XCircleIcon: IconComponent
```

Failure.

**Related:** [IconComponent](/reference/studio-sdk/components#iconcomponent)

## baseNameOf

```ts theme={null}
function baseNameOf(name: string): string
```

The base tool name a variant belongs to: the substring before the first
underscore, or the whole name when it has none. `tool`, `tool_a`, `tool_a_b`
all resolve to `tool`; `x_chain` and `x_batch` both resolve to `x`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `string` | — | — |

## buildSubject

```ts theme={null}
function buildSubject(
  v: { key: string; kind: string; target: string },
): { ok: true; subject: { key: string; kind: string; target_kind: "agent" | "tool"; target_name: string } | null } | { message: string; ok: false }
```

Build a `StateSubject` from the sub-form values: `null` when untouched (no
subject), a subject when target, kind and key are all set, or a loud failure when only
some are — never a silently dropped partial subject. The target splits on its FIRST
colon, so a target name may itself contain one.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `v` | `{ key: string; kind: string; target: string }` | — | — |

## buildTagVocabulary

```ts theme={null}
function buildTagVocabulary<T>(
  items: readonly T[],
  getTags: (item: T) => readonly string[],
  selectedTags: readonly string[],
  untaggedLabel: string,
): TagVocabularyEntry[]
```

The tag vocabulary over `items`, name-sorted, plus an untagged pseudo-tag
(labelled `untaggedLabel`) when any item is untagged; a selected token whose
items vanished still appears (count 0) so it can be cleared.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `items` | `readonly T[]` | — | — |
| `getTags` | `(item: T) => readonly string[]` | — | — |
| `selectedTags` | `readonly string[]` | — | — |
| `untaggedLabel` | `string` | — | — |

**Related:** [TagVocabularyEntry](/reference/studio-sdk/components#tagvocabularyentry)

## childFolders

```ts theme={null}
function childFolders(folders: readonly Folder[], parentId: string | null): Folder[]
```

The subfolders directly under `parentId` (`null` = the root directory), name-sorted.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `folders` | `readonly Folder[]` | — | — |
| `parentId` | `string \| null` | — | — |

**Related:** [Folder](/reference/studio-sdk/components#folder)

## diffJson

```ts theme={null}
function diffJson(before: unknown, after: unknown): JsonDiffRow[]
```

The pure structural diff — every leaf difference between `before` and `after`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `before` | `unknown` | — | — |
| `after` | `unknown` | — | — |

**Related:** [JsonDiffRow](/reference/studio-sdk/components#jsondiffrow)

## folderPathTo

```ts theme={null}
function folderPathTo(folders: readonly Folder[], folderId: string | null): Folder[]
```

The ordered ancestor path from the root down to (and including) `folderId`, for a
breadcrumb. `null` is the root (an empty path). The walk is bounded by the folder
count, so a cyclic or dangling chain truncates instead of looping.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `folders` | `readonly Folder[]` | — | — |
| `folderId` | `string \| null` | — | — |

**Related:** [Folder](/reference/studio-sdk/components#folder)

## formatRangeLabel

```ts theme={null}
function formatRangeLabel(
  value: DateRangeValue,
  presets: readonly DateRangePreset[],
): string
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `DateRangeValue` | — | — |
| `presets` | `readonly DateRangePreset[]` | `DEFAULT_DATE_RANGE_PRESETS` | — |

**Related:** [DateRangePreset](/reference/studio-sdk/components#daterangepreset), [DateRangeValue](/reference/studio-sdk/components#daterangevalue)

## groupByKind

```ts theme={null}
function groupByKind(
  extensions: readonly ({ kind: string; multiple: boolean; name: string })[],
): ExtensionKindGroup[]
```

Group a flat extension list by `kind`, for the picker. Groups are ordered by
kind and each group's members by name, so the render order is stable regardless
of the server's list order. Each group carries its kind's served `multiple`; a kind
whose entries disagree is a catalog fault and throws.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `extensions` | `readonly ({ kind: string; multiple: boolean; name: string })[]` | — | — |

**Related:** [ExtensionKindGroup](/reference/studio-sdk/components#extensionkindgroup)

## groupIntoFamilies

```ts theme={null}
function groupIntoFamilies(
  extensions: readonly ({ kind: string; multiple: boolean; name: string })[],
): ExtensionFamily[]
```

Group a flat extension list into families keyed by base tool name. Families
are ordered by base name and each family's members by full name, so the render
order is stable regardless of the server's list order.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `extensions` | `readonly ({ kind: string; multiple: boolean; name: string })[]` | — | — |

**Related:** [ExtensionFamily](/reference/studio-sdk/components#extensionfamily)

## isExecutionKeyListEmpty

```ts theme={null}
function isExecutionKeyListEmpty(query: ExecutionKeyQuery): boolean
```

Resolved, and holding no key at all.

**Props**

| Prop | Type | Description |
| - | - | - |
| `data` | `({ condition: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; description: string; orphaned: boolean; policy_data: Record<string, unknown> \| null; principal: { display_name: string; kind: "human" \| "service"; user_id: string } \| null; scopes: string[] \| null; user_id: string })[] \| undefined` | — |
| `error` | `unknown` | — |
| `isError` | `boolean` | — |
| `isPending` | `boolean` | — |
| `isSuccess` | `boolean` | — |
| `refetch` | `() => void` | — |

**Related:** [ExecutionKeyQuery](/reference/studio-sdk/components#executionkeyquery)

## isRenderableMediaSrc

```ts theme={null}
function isRenderableMediaSrc(
  url: string,
  grammar: ServedMediaGrammar,
  allowDataImage: boolean,
): boolean
```

The media src gate: a media element renders ONLY for an `https:` URL, the
platform's own served-media reference (a relative `MEDIA_ROUTE_PREFIX + <id>`),
or — when the caller opts in with `allowDataImage` — an inline `data:image/*` URI.
`isSafeHttpUrl` is TIGHTENED to https-only here (it alone also admits `http:`,
which the Studio CSP `img-src`/`media-src` blocks and the contract never emits);
the served-media branch pins a well-formed platform media id (a relative url
`isSafeHttpUrl` cannot parse). `allowDataImage` defaults OFF: only a sink that
stores media RAW (never substituted to a served reference) opts in, and even then
ONLY `data:image/*` is admitted — a `data:` of any other type (`data:text/html`,
an SVG document, …) is ALWAYS blocked. `http:`, `javascript:`, a non-image
`data:`, and any other-shaped relative url fail every branch → a loud blocked
item. The gate keys on the reference form; `resolveMediaSrc` joins an
admitted reference to the API base for the actual load.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `url` | `string` | — | — |
| `grammar` | `ServedMediaGrammar` | — | — |
| `allowDataImage` | `boolean` | `false` | — |

**Related:** [ServedMediaGrammar](/reference/studio-sdk/components#servedmediagrammar)

## isSafeHttpUrl

```ts theme={null}
function isSafeHttpUrl(url: string): boolean
```

True only for an absolute `http://`/`https://` URL. Everything else is unsafe.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `url` | `string` | — | — |

## isServedMediaUrl

```ts theme={null}
function isServedMediaUrl(url: string, grammar: ServedMediaGrammar): boolean
```

Whether `url` is the platform's own served-media reference: a relative
`MEDIA_ROUTE_PREFIX + <id>` whose id matches `MEDIA_ID_PATTERN` whole. A served
reference is same-origin to the API base (`resolveMediaSrc`) and leaks no page
context on load, so a sink with no per-element referrer control (`<audio>`/`<video>`,
where `referrerPolicy` is not a valid attribute) admits ONLY this form.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `url` | `string` | — | — |
| `grammar` | `ServedMediaGrammar` | — | — |

**Related:** [ServedMediaGrammar](/reference/studio-sdk/components#servedmediagrammar)

## kindVariant

```ts theme={null}
function kindVariant(kind: string): string
```

Map a serialized extension `kind` to a Badge variant. Known skeleton kinds get
a themed color; any unrecognized kind falls back to the neutral variant (the
Badge itself also neutral-fallbacks, but choosing here keeps the mapping
explicit and testable).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `string` | — | — |

## matchesSelectedTags

```ts theme={null}
function matchesSelectedTags(
  itemTags: readonly string[],
  selected: ReadonlySet<string>,
): boolean
```

OR semantics: an empty selection matches everything; otherwise an item
matches when it carries any selected tag, or is untagged and UNTAGGED\_TOKEN
is selected.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `itemTags` | `readonly string[]` | — | — |
| `selected` | `ReadonlySet<string>` | — | — |

## normalizeCustomRange

```ts theme={null}
function normalizeCustomRange(
  fromInput: string,
  toInput: string,
  now: Date,
): { from: string; to: string }
```

A raw from/to pair resolved to a clean absolute range. Order matters: SWAP the
reversed pair first (earlier instant becomes start), THEN cap both ends at `now` —
capping first can leave a future instant on the post-swap end. The end is
INCLUSIVE of its minute, extended to `:59.999`, so `23:59` reaches the day's end.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `fromInput` | `string` | — | — |
| `toInput` | `string` | — | — |
| `now` | `Date` | — | — |

## openTargetProps

```ts theme={null}
function openTargetProps(props: OpenTargetOptions): OpenTargetProps
```

Build the whole-target open props for one entry. See the module doc for the
contract; pass `onOpen: undefined` to get an inert entry (empty props).

**Props**

| Prop | Type | Description |
| - | - | - |
| `ignoreWithin?` | `string` | Extra selector(s) that also count as "nested interactive" for THIS surface,  merged with the built-in set. Use it for a marked non-`button`/`a` subtree  that owns its own clicks (e.g. an expandable preview keyed by a data  attribute). Standard CSS selector syntax, comma-separated. |
| `keyboard?` | `boolean` | Make the entry itself keyboard-operable: a `tabIndex: 0` focus stop with  Enter/Space activation. Leave off when a nested interactive element already  carries the accessible path (see the keyboard note above) — adding it there  would create a duplicate tab stop. |
| `onOpen` | `() => void \| undefined` | Open the entry. `undefined` disables the affordance entirely — the helper  returns empty props so the element stays inert (no cursor, no handlers),  which lets a caller wire the whole thing behind an optional prop. |

**Related:** [OpenTargetOptions](/reference/studio-sdk/components#opentargetoptions), [OpenTargetProps](/reference/studio-sdk/components#opentargetprops)

## overlayDetailsPatch

```ts theme={null}
function overlayDetailsPatch(
  value: OverlayDetails,
): { display_name: string | null; tags: string[] }
```

The merge-patch a display-name + tags write sends: ONLY these two fields.

**Props**

| Prop | Type | Description |
| - | - | - |
| `displayName` | `string` | The raw display-name draft (unblank-normalized only at write time). |
| `tags` | `readonly string[]` | — |

**Related:** [OverlayDetails](/reference/studio-sdk/components#overlaydetails)

## parseMarkdown

```ts theme={null}
function parseMarkdown(markdown: string): MarkdownBlock[]
```

Folds markdown source into an ordered list of blocks. Pure and total: any
string parses, and text that matches no block construct becomes a paragraph
rather than being discarded.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `markdown` | `string` | — | — |

**Related:** [MarkdownBlock](/reference/studio-sdk/components#markdownblock)

## resolveMediaSrc

```ts theme={null}
function resolveMediaSrc(url: string, baseUrl: string, grammar: ServedMediaGrammar): string
```

The URL an admitted media element actually loads. An `https:` url is already
absolute and is returned unchanged. A served-media reference is RELATIVE and is
joined to the API origin (`baseUrl`) — NOT the SPA page origin: in a cross-origin
deployment the two differ, and a page-relative src would resolve against Studio
and 404. An empty `baseUrl` (same-origin deployment) leaves the reference
relative, which is correct; a configured base's trailing slash is stripped so the
join never double-slashes.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `url` | `string` | — | — |
| `baseUrl` | `string` | — | — |
| `grammar` | `ServedMediaGrammar` | — | — |

**Related:** [ServedMediaGrammar](/reference/studio-sdk/components#servedmediagrammar)

## safeHttpUrl

```ts theme={null}
function safeHttpUrl(href: string): string | undefined
```

The absolute http(s) URL `href` denotes, or `undefined` when it denotes none.

The `//` is required rather than inferred from a successful `new URL()`,
because for a scheme that matches the document's own, the authority-less
spelling is a PATH: an anchor with `href="https:/settings"` on an https page
navigates to `/settings` on the CURRENT origin, while `new URL()` with no base
reads the same string as the host `settings`. Only the `//` form means the same
thing to both.

An absolute http(s) URL carrying `user:pass@` userinfo is rejected too: `.href`
re-serialization preserves the userinfo (unlike host tricks), so
`https://trusted.com@evil.com` would render as trusted.com yet navigate to
evil.com.

Callers render the returned string rather than their input, so the URL that was
judged is always the URL that is navigated.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `href` | `string` | — | — |

## templatedTextSummary

```ts theme={null}
function templatedTextSummary(
  value: { content?: string; id?: string; kwargs?: Record<string, unknown> } | null,
): string
```

A short one-line rendering of a templated-text value, for read-only summaries.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `{ content?: string; id?: string; kwargs?: Record<string, unknown> } \| null` | — | — |

## toSubjectTargetOptions

```ts theme={null}
function toSubjectTargetOptions(
  routes: readonly ({ target_kind: string; target_name: string })[],
): SubjectTargetOption[]
```

Map the conversation routes read to the target select's options.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `routes` | `readonly ({ target_kind: string; target_name: string })[]` | — | — |

**Related:** [SubjectTargetOption](/reference/studio-sdk/components#subjecttargetoption)

## useFieldControl

```ts theme={null}
function useFieldControl(): FieldControlProps
```

Read the enclosing Field's wiring.

`id` and `aria-describedby` are `undefined` both when there is no Field AND
inside a group `Field`: a group has no single element to carry them, and the
group container itself already carries the name and the description. Only
`aria-invalid` still crosses that boundary, because `role="group"` does not
support it (ARIA 1.2), so the control is the sole place an errored group can
expose its invalid state.

**Related:** [FieldControlProps](/reference/studio-sdk/components#fieldcontrolprops)

## useFillViewport

```ts theme={null}
function useFillViewport(): void
```

Opt the current page into full-height fill mode for as long as it is mounted.
The shell fills `<main>` to the viewport and lets the page's own root flex or
`height: 100%` down the chain. Must be called under a `PageFillProvider`
(the shell mounts one); outside it there is no wrapper to modify, so it throws
rather than silently do nothing.

## useOverflowRegion

```ts theme={null}
function useOverflowRegion(
  ref: Ref<HTMLElement> | undefined,
  label: string,
  axis: OverflowAxis,
): OverflowRegionAttributes
```

The conditional region attributes for a scrolling box, alongside the ref that
names it. The ref must go on the scrolling box ITSELF — a `<pre>`, a JSON
pane, or the `div` `ScrollRegion` renders. Use the hook when wrapping the
content in a `ScrollRegion` would give the surface a second scroller.

The box is measured as it is attached, whenever it or any child resizes, and
whenever its content changes — replaced, appended, or edited in place. A
replaced child is a NEW element, so the registration is re-pointed at the
current children before each measurement, adding and dropping only the ones
that actually changed; both sides of that are registrations on the shared
observers, not observers of this mount's own. The only DOM change a
measurement can cause is the region ATTRIBUTES this hook returns, and
attributes are deliberately left unobserved — that, not an absence of
mutation, is what stops the pair from re-triggering each other.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `ref` | `Ref<HTMLElement> \| undefined` | — | a consumer ref that wants the same element, or `undefined`. |
| `label` | `string` | — | its accessible name, applied only while it actually scrolls. |
| `axis` | `OverflowAxis` | `'horizontal'` | the dimension to measure overflow on (`horizontal` by default;   `vertical` for a bounded, capped-height box that scrolls down). |

**Related:** [OverflowAxis](/reference/studio-sdk/components#overflowaxis), [OverflowRegionAttributes](/reference/studio-sdk/components#overflowregionattributes)

## usePageFillActive

```ts theme={null}
function usePageFillActive(): boolean
```

Whether any mounted page currently asks for fill mode — the shell's cue to add
the fill modifiers to `<main>` and the page wrapper.

## useProseScrollRegions

```ts theme={null}
function useProseScrollRegions(labels?: ProseScrollLabels): RefCallback<HTMLElement>
```

Instruments the scrollable surfaces under the element the returned ref is
attached to — every `<table>` and every `<pre>` — as scroll regions. React
cannot wrap markup it did not create, so this walks the DOM instead. A table
is moved into a `div.tai-scroll-region` (once — the pass is idempotent)
because the table itself is not the scrolling box; a `<pre>` already IS its
own scrolling box, so it is instrumented in place. Either way the scrolling
element carries the same conditional `tabindex`/`role`/`aria-label` as
`ScrollRegion`.

The name is the nearest heading preceding the surface — read for all of them
in one document-order pass — so a reader landing on the region hears which
section it belongs to; `labels` covers a surface with no heading above it, and
a name shared by several surfaces is numbered so no two regions answer to the
same one.

The pass runs from the ref callback rather than an effect, which puts it in
the commit phase, BEFORE the browser paints: `.tai-prose table` is
`width: 100%` with no overflow of its own — the scroller exists only on the
wrapper this builds — so a pass that ran after paint would show one frame at
320/360 px with the table overflowing the document, then jolt sideways. A
passive-effect probe measured exactly that: at first paint wrappers=0 and the
table's parent was `.tai-prose`.

Injected HTML is replaced wholesale when its source changes, so the pass is
re-run from a `MutationObserver` on the subtree rather than on attachment
alone.

**Props**

| Prop | Type | Description |
| - | - | - |
| `pre?` | `string` | — |
| `table?` | `string` | — |

**Related:** [ProseScrollLabels](/reference/studio-sdk/components#prosescrolllabels)

## useRegisterDirty

```ts theme={null}
function useRegisterDirty(dirty: boolean): void
```

Report an editor's dirty state to the enclosing `DirtyGuardBoundary` (which
`GuardedTabs` also provides). A no-op outside a boundary (an editor rendered
standalone, e.g. in isolation tests) so the hook is always safe to call.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `dirty` | `boolean` | — | — |

## useSubjectFields

```ts theme={null}
function useSubjectFields(): { error: string | null; key: string; kind: string; open: boolean; setError: Dispatch<SetStateAction<string | null>>; setKey: Dispatch<SetStateAction<string>>; setKind: Dispatch<SetStateAction<string>>; setOpen: Dispatch<SetStateAction<boolean>>; setTarget: Dispatch<SetStateAction<string>>; target: string }
```

Subject field state + setters + the collapse toggle. The host feature owns the
open-gated conversation-targets query and derives `targetOptions` from it.

## useViewMode

```ts theme={null}
function useViewMode(
  surface: string,
  fallback: ViewMode,
): readonly [ViewMode, (mode: ViewMode) => void]
```

The persisted view mode for one `surface` (a stable key like `'tools'`). Returns
the stored choice or `fallback` when none is set, and a setter that writes through
to `localStorage`. Storage failures degrade to in-memory only — never a thrown
boot, matching the theme preference's defensive reads/writes.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `surface` | `string` | — | — |
| `fallback` | `ViewMode` | `'list'` | — |

**Related:** [ViewMode](/reference/studio-sdk/components#viewmode)


# Hooks
Source: https://docs.tai42.ai/reference/studio-sdk/hooks

The React hooks and providers every feature builds on — API access, theme, auth, and the interactions stream.

The React hooks and providers every feature builds on — API access, theme, auth, and the interactions stream.

## ApiProvider

```ts theme={null}
const ApiProvider: Provider<ApiClient | null>
```

**Related:** [ApiClient](/reference/studio-sdk/utilities#apiclient)

## AuthProvider

```ts theme={null}
function AuthProvider(
  props: { children: ReactNode },
): FunctionComponentElement<ProviderProps<AuthState | null>>
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `props` | `{ children: ReactNode }` | — | — |

**Related:** [AuthState](/reference/studio-sdk/hooks#authstate)

## AuthState

```ts theme={null}
interface AuthState
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `isAuthenticated` | `boolean` | — |
| `login` | `(token: string, remember: boolean) => void` | Store the key; `remember` persists to sessionStorage for this device. |
| `logout` | `() => void` | — |
| `token` | `string \| null` | — |

## Breakpoint

```ts theme={null}
type Breakpoint = "phone" | "compact" | "medium" | "full"
```

## BreakpointState

```ts theme={null}
interface BreakpointState
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `band` | `Breakpoint` | — |
| `isPhone` | `boolean` | True below 640 — the `phone` band, where a surface has one column to work in. |
| `isSinglePane` | `boolean` | True below 1024 — too narrow for two panes side by side. |

**Related:** [Breakpoint](/reference/studio-sdk/hooks#breakpoint)

## CapabilityContextValue

```ts theme={null}
interface CapabilityContextValue
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `retry` | `() => void` | Re-fetch the projection (the nav-region `ErrorState`'s retry action). |
| `state` | `CapabilityState` | — |

**Related:** [CapabilityState](/reference/studio-sdk/hooks#capabilitystate)

## CapabilityProvider

```ts theme={null}
function CapabilityProvider(
  props: { children: ReactNode },
): FunctionComponentElement<ProviderProps<CapabilityContextValue | null>>
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `props` | `{ children: ReactNode }` | — | — |

**Related:** [CapabilityContextValue](/reference/studio-sdk/hooks#capabilitycontextvalue)

## CapabilityState

```ts theme={null}
type CapabilityState = { status: "loading" } | { projection: MeProjection; status: "ready" } | { error: unknown; status: "failed" }
```

## InteractionsStreamOptions

```ts theme={null}
interface InteractionsStreamOptions
```

The inputs the caller drives the tail-only stream with.

**Properties**

| Property | Type | Description |
| - | - | - |
| `onResync` | `() => boolean \| Promise<boolean>` | Refetch `seed`. Called on every (re)connect ONLY — the tail carries no backlog, so this reconciles anything missed while disconnected. A live delta never calls it: the overlay updates the list and the derived `count` in place. MUST resolve `true` only when the refetch LANDED a fresh `total`, and `false` when it failed: the hook advances `countEpoch` only on `true`, so terminals and adds already folded into the fresh `total` are not applied to the count again, while after a failed refetch the prior-epoch deltas keep applying against the unchanged prior total instead of being discarded against a stale one. |
| `seed` | `readonly ({ answer_format: "form" \| "select" \| "external" \| "text" \| "free" \| "confirm"; audience: string \| null; channel: string \| null; created_at: string; format_payload: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>, z.ZodTransform<Record<string, unknown>, Record<string, unknown> \| null \| undefined>>; group_id: string; interaction_id: string; media: ({ caption: string \| null; filename: string \| null; kind: "audio" \| "link" \| "video" \| "document" \| "image"; url: string })[] \| null; origin: string \| null; question: string; recipient: string \| null; sensitive: boolean; server_verified: boolean \| null; timeout_at: string })[]` | The pending set from the paged `GET /api/interactions` door — the base the live tail overlays. A stable reference between refetches (memoize it upstream); a new reference re-merges but does NOT reopen the stream. |
| `total` | `number` | The door's authoritative pending TOTAL for the current `seed` (the paged response's `total`). The published `count` derives the live pending tally from this plus the overlay delta, so the badge stays live without a refetch. |

## InteractionsStreamState

```ts theme={null}
interface InteractionsStreamState
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `connected` | `boolean` | — |
| `count` | `number` | The live pending count: the seed `total` adjusted by the overlay delta stamped at or after the last landed resync's epoch (adds not in the seed, minus one per terminal id). Stays live without a refetch; a delta stamped before `countEpoch` is already reflected in `total` and not applied again. |
| `disabled` | `boolean` | The interactions store is not configured on this deployment: the stream answered with a terminal 501 `interactions-not-configured`. Reconnection is abandoned and the consumer renders the muted OFF state instead of a red error. |
| `error` | `Error \| null` | — |
| `interactions` | `StreamInteraction[]` | — |

**Related:** [StreamInteraction](/reference/studio-sdk/hooks#streaminteraction)

## StreamInteraction

```ts theme={null}
type StreamInteraction = Interaction & { answered: boolean }
```

A live interaction plus the client-maintained `answered` flag.

## SystemKindsProvider

```ts theme={null}
function SystemKindsProvider(
  props: { children: ReactNode },
): FunctionComponentElement<ProviderProps<SystemKindsState | null>>
```

Fetch the kind-status table once the caller is authenticated and hold it as SDK
state. Gated on `isAuthenticated` (the table is an authed read), so the login
screen never fires a doomed request; a fetch failure settles into `failed`
QUIETLY — no unauthorized routing, no loud error — because the consuming
affordance falls back to its reactive OFF handling.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `props` | `{ children: ReactNode }` | — | — |

**Related:** [SystemKindsState](/reference/studio-sdk/hooks#systemkindsstate)

## SystemKindsState

```ts theme={null}
type SystemKindsState = { status: "loading" } | { kinds: readonly KindStatus[]; status: "ready" } | { error: unknown; status: "failed" }
```

## Theme

```ts theme={null}
type Theme = "light" | "dark"
```

## ThemePreference

```ts theme={null}
type ThemePreference = "light" | "dark" | "system"
```

## ThemeProvider

```ts theme={null}
function ThemeProvider(
  props: { children: ReactNode },
): FunctionComponentElement<ProviderProps<ThemeState | null>>
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `props` | `{ children: ReactNode }` | — | — |

**Related:** [ThemeState](/reference/studio-sdk/hooks#themestate)

## ThemeState

```ts theme={null}
interface ThemeState
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `preference` | `ThemePreference` | The operator's choice: a pinned theme, or `'system'` to follow the OS. |
| `setPreference` | `(preference: ThemePreference) => void` | Set the preference and persist it. The only path that writes storage. |
| `setTheme` | `(theme: Theme) => void` | Pin an explicit theme (persists) — a preference shortcut kept for callers. |
| `theme` | `Theme` | The resolved theme the tokens key off — always concrete, never `'system'`. |
| `toggle` | `() => void` | Flip between the two pinned themes off the current resolved theme (persists). |

**Related:** [Theme](/reference/studio-sdk/hooks#theme), [ThemePreference](/reference/studio-sdk/hooks#themepreference)

## ToolDisplayNamesContextValue

```ts theme={null}
interface ToolDisplayNamesContextValue
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `reload` | `() => void` | Re-fetch the overlay (drives the app-level refresh after a display-name edit). |
| `state` | `ToolDisplayNamesState` | — |

**Related:** [ToolDisplayNamesState](/reference/studio-sdk/hooks#tooldisplaynamesstate)

## ToolDisplayNamesProvider

```ts theme={null}
function ToolDisplayNamesProvider(
  props: { children: ReactNode },
): FunctionComponentElement<ProviderProps<ToolDisplayNamesContextValue | null>>
```

Fetch the tool-meta overlay once the caller is authenticated and hold its
display-name map as SDK state. Gated on `isAuthenticated` (the overlay is an authed
read), so the login screen never fires a doomed request; a fetch failure settles
into `failed` QUIETLY, because the consuming pickers fall back to the bare raw name.
`reload` re-fetches on demand, so an app-level display-name write refreshes every
picker without a remount.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `props` | `{ children: ReactNode }` | — | — |

**Related:** [ToolDisplayNamesContextValue](/reference/studio-sdk/hooks#tooldisplaynamescontextvalue)

## ToolDisplayNamesState

```ts theme={null}
type ToolDisplayNamesState = { status: "loading" } | { names: Readonly<Record<string, string>>; status: "ready" } | { error: unknown; status: "failed" }
```

## UnauthorizedProvider

```ts theme={null}
const UnauthorizedProvider: Provider<() => void>
```

## coversAnyRoute

```ts theme={null}
function coversAnyRoute(
  projection: { admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string | null; principal: { display_name: string; kind: "human" | "service"; user_id: string } | null; public_resource_id: string; route_patterns: ({ open_prefix: string | null; pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ access_pattern: string; mount_url: string; slug: string; tools: string[]; transport: string })[]; tools: string[]; user_id: string },
  prefixes: readonly string[],
): boolean
```

Whether the projection reaches ANY route under one of `prefixes` — the
declarative test behind nav filtering and plugin `requiredCapabilities`. A
concrete `routes[].path` covers a prefix when it is that prefix or a
segment-nested descendant of it; a dynamic `route_patterns[]` entry covers a
prefix through its served `open_prefix` — the literal the server rules every
path starting with is reachable — when it overlaps the prefix at a segment
boundary. A `null` open prefix (a pattern whose matched set is not a clean
prefix) covers nothing by prefix: under-showing is safe, over-showing is the bug.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `projection` | `{ admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string \| null; principal: { display_name: string; kind: "human" \| "service"; user_id: string } \| null; public_resource_id: string; route_patterns: ({ open_prefix: string \| null; pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ access_pattern: string; mount_url: string; slug: string; tools: string[]; transport: string })[]; tools: string[]; user_id: string }` | — | — |
| `prefixes` | `readonly string[]` | — | — |

## coversRoute

```ts theme={null}
function coversRoute(
  projection: { admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string | null; principal: { display_name: string; kind: "human" | "service"; user_id: string } | null; public_resource_id: string; route_patterns: ({ open_prefix: string | null; pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ access_pattern: string; mount_url: string; slug: string; tools: string[]; transport: string })[]; tools: string[]; user_id: string },
  path: string,
  method: string,
): boolean
```

Whether the projection reaches a specific WRITE route — an EXACT `path` whose
admitted `methods` include `method`. This is the method-aware companion to
`coversAnyRoute`: a read/nav surface gates path-only (any method reaching a
prefix means the surface is navigable), but an action that issues `method path`
must gate on the method too, or a caller whose jq fence admits only GET on `path`
would be shown a control that 403s on submit (projection ⊆ gate).

Only concrete `routes` are consulted: dynamic `route_patterns` carry no method, so
no write capability can be soundly inferred from them, and a synthetic TOTAL
(admin) projection carries no concrete `routes` at all — callers short-circuit it
with `isFullProjection` before reaching here. Under-showing is safe (the
server stays the authority); over-showing an action the gate denies is the bug.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `projection` | `{ admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string \| null; principal: { display_name: string; kind: "human" \| "service"; user_id: string } \| null; public_resource_id: string; route_patterns: ({ open_prefix: string \| null; pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ access_pattern: string; mount_url: string; slug: string; tools: string[]; transport: string })[]; tools: string[]; user_id: string }` | — | — |
| `path` | `string` | — | — |
| `method` | `string` | — | — |

## coversWrite

```ts theme={null}
function coversWrite(state: CapabilityState, path: string, method: string): boolean
```

Whether a WRITE control may be shown/enabled for this caller — the fail-closed,
method-aware gate the features fold together with any deployment-level read-only flag
(the projection ⊆ gate invariant, in one place). It is `true` ONLY once the projection
is `ready` AND either it is a full (admin / gate-off) projection or it reaches
`method path`. While the projection is loading/failed it is `false` — a write control
never enables before the gate is known (fail closed; not-ready ⇒ disabled/read-only).

Only concrete `routes` carry methods, so a DYNAMIC (templated) write route — one the
projection can represent only as a method-less `route_patterns` row — reads `false` for
every non-admin caller and degrades that control to read-only. Under-showing is safe
(the server stays the authority); over-showing a write the gate denies is the bug.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `state` | `CapabilityState` | — | — |
| `path` | `string` | — | — |
| `method` | `string` | — | — |

**Related:** [CapabilityState](/reference/studio-sdk/hooks#capabilitystate)

## isFullProjection

```ts theme={null}
function isFullProjection(
  projection: { admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string | null; principal: { display_name: string; kind: "human" | "service"; user_id: string } | null; public_resource_id: string; route_patterns: ({ open_prefix: string | null; pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ access_pattern: string; mount_url: string; slug: string; tools: string[]; transport: string })[]; tools: string[]; user_id: string },
): boolean
```

Whether the projection is the synthetic TOTAL projection — the admin session
(the condition-free `"*"` discriminator) and the gate-off local-dev
projection alike. This is `projection.admin === true` and NOTHING else: a
seeded editor/viewer carries `["*"]` scopes PLUS a jq fence, so keying on `"*"`
scopes would hand every editor/viewer the unfiltered nav and a wall of 403s on
the admin routes their fence denies. Keying on `admin` makes editor/viewer
SCOPED sessions whose nav is filtered by their jq-exact `routes`, which is
exactly right — and the gate-off synthetic projection (`admin: true`, empty
`routes`) still reads as full, so an AC-disabled deployment shows everything.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `projection` | `{ admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string \| null; principal: { display_name: string; kind: "human" \| "service"; user_id: string } \| null; public_resource_id: string; route_patterns: ({ open_prefix: string \| null; pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ access_pattern: string; mount_url: string; slug: string; tools: string[]; transport: string })[]; tools: string[]; user_id: string }` | — | — |

## toolDisplayLabel

```ts theme={null}
function toolDisplayLabel(names: Readonly<Record<string, string>>, rawName: string): string
```

The option label for a raw tool name under a display-name map: `Display (raw)` when
a display name maps the name and is non-empty AND differs from the raw name, else
the bare raw name. Shared so every tool picker labels identically.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `names` | `Readonly<Record<string, string>>` | — | the raw-name → display-name map (from useToolDisplayNames). |
| `rawName` | `string` | — | the raw tool name to label. |

## useApi

```ts theme={null}
function useApi(): ApiClient
```

**Related:** [ApiClient](/reference/studio-sdk/utilities#apiclient)

## useAuth

```ts theme={null}
function useAuth(): AuthState
```

**Related:** [AuthState](/reference/studio-sdk/hooks#authstate)

## useBreakpoint

```ts theme={null}
function useBreakpoint(): BreakpointState
```

**Related:** [BreakpointState](/reference/studio-sdk/hooks#breakpointstate)

## useCanWrite

```ts theme={null}
function useCanWrite(path: string, method: string): boolean
```

Whether a WRITE control may be shown for the current caller — the single boundary
primitive a feature calls to hide a control whose `method path` the caller's
projection cannot reach. It reads the live capability state and folds it through
`coversWrite`: `true` only once the projection is `ready` AND it is a full
(admin / gate-off) projection or it reaches `method path`; while the projection is
loading/failed it is `false` (fail closed — no write control before the gate is
known). `method` defaults to `POST`, the common write verb; pass the exact verb for
a PUT/PATCH/DELETE control.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `string` | — | — |
| `method` | `string` | `'POST'` | — |

## useCapabilities

```ts theme={null}
function useCapabilities(): CapabilityContextValue
```

**Related:** [CapabilityContextValue](/reference/studio-sdk/hooks#capabilitycontextvalue)

## useFeatureOff

```ts theme={null}
function useFeatureOff(kind: string): boolean
```

Whether `kind` is reported OFF by the kind-status table — the single proactive
predicate a write affordance folds in to hide itself before a doomed write. It is
`true` ONLY once the table is `ready` AND that kind's row carries `state: 'off'`;
while the table is loading/failed, no provider is mounted, or the kind is unknown,
it is `false` (treat as not-off until known — under-hiding is safe, the reactive
501 backstop still catches a genuinely-off feature).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `string` | — | — |

## useFeatureOffMessage

```ts theme={null}
function useFeatureOffMessage(kind: string): string | null
```

The OFF row's server `detail` for `kind` — the proactive counterpart to a write
refusal's message, so a proactively-hidden surface shows the SERVER's own
remediation line rather than a client-composed env-var string. `null` whenever the
kind is not reported OFF (table loading/failed, no provider, unknown kind, or the
kind is on), mirroring `useFeatureOff`'s not-off-until-known default.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `kind` | `string` | — | — |

## useInteractionsStream

```ts theme={null}
function useInteractionsStream(options: InteractionsStreamOptions): InteractionsStreamState
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `onResync` | `() => boolean \| Promise<boolean>` | Refetch `seed`. Called on every (re)connect ONLY — the tail carries no backlog, so this reconciles anything missed while disconnected. A live delta never calls it: the overlay updates the list and the derived `count` in place. MUST resolve `true` only when the refetch LANDED a fresh `total`, and `false` when it failed: the hook advances `countEpoch` only on `true`, so terminals and adds already folded into the fresh `total` are not applied to the count again, while after a failed refetch the prior-epoch deltas keep applying against the unchanged prior total instead of being discarded against a stale one. |
| `seed` | `readonly ({ answer_format: "form" \| "select" \| "external" \| "text" \| "free" \| "confirm"; audience: string \| null; channel: string \| null; created_at: string; format_payload: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>, z.ZodTransform<Record<string, unknown>, Record<string, unknown> \| null \| undefined>>; group_id: string; interaction_id: string; media: ({ caption: string \| null; filename: string \| null; kind: "audio" \| "link" \| "video" \| "document" \| "image"; url: string })[] \| null; origin: string \| null; question: string; recipient: string \| null; sensitive: boolean; server_verified: boolean \| null; timeout_at: string })[]` | The pending set from the paged `GET /api/interactions` door — the base the live tail overlays. A stable reference between refetches (memoize it upstream); a new reference re-merges but does NOT reopen the stream. |
| `total` | `number` | The door's authoritative pending TOTAL for the current `seed` (the paged response's `total`). The published `count` derives the live pending tally from this plus the overlay delta, so the badge stays live without a refetch. |

**Related:** [InteractionsStreamOptions](/reference/studio-sdk/hooks#interactionsstreamoptions), [InteractionsStreamState](/reference/studio-sdk/hooks#interactionsstreamstate)

## useOnUnauthorized

```ts theme={null}
function useOnUnauthorized(): () => void
```

## useReloadToolDisplayNames

```ts theme={null}
function useReloadToolDisplayNames(): () => void
```

Re-fetch the display-name overlay. A surface that writes a display name calls this
so the app-level provider — and every picker reading it — refreshes alongside the
surface's own list invalidation. A no-op when no provider is mounted.

## useSystemKinds

```ts theme={null}
function useSystemKinds(): SystemKindsState
```

The live kind-status state. Falls back to `loading` when no provider is mounted, so
a consumer rendered outside the shell reads every kind as not-off rather than
throwing — the fail-open default this proactive-hiding idiom relies on.

**Related:** [SystemKindsState](/reference/studio-sdk/hooks#systemkindsstate)

## useTheme

```ts theme={null}
function useTheme(): ThemeState
```

**Related:** [ThemeState](/reference/studio-sdk/hooks#themestate)

## useToolDisplayNames

```ts theme={null}
function useToolDisplayNames(): Readonly<Record<string, string>>
```

The live raw-name → display-name map — `{}` while the overlay is loading/failed, no
provider is mounted, or no row carries a display name. A tool picker folds this into
its option labels; an unmapped name reads the bare raw name.


# Host & testing
Source: https://docs.tai42.ai/reference/studio-sdk/host-testing

The host-only registry API (loadPlugin / getContributions) and the test-only reset.

The host-only registry API (loadPlugin / getContributions) and the test-only reset.

## LoadedPlugin

```ts theme={null}
interface LoadedPlugin
```

Identity of a successfully-loaded plugin, for host chrome that must attribute a
contribution to its origin (e.g. the shell's provenance badge on plugin nav). The
`name` is the same id the registry stamps on every contribution (`pluginId`); the
`version` comes from the plugin's manifest.

**Properties**

| Property | Type | Description |
| - | - | - |
| `name` | `string` | — |
| `version` | `string` | — |

## PluginContributionsSnapshot

```ts theme={null}
interface PluginContributionsSnapshot
```

What `usePluginContributions` returns: the load status and the registry.

**Properties**

| Property | Type | Description |
| - | - | - |
| `contributions` | `PluginContributions` | The committed contributions, meaningful only when `status === 'ready'`. |
| `status` | `"loading" \| "ready" \| "idle"` | The load pass's status; contributions are only complete once it is `'ready'`. |

**Related:** [PluginContributions](/reference/studio-sdk/plugin-api#plugincontributions)

## PluginLoadInputs

```ts theme={null}
interface PluginLoadInputs
```

What the host knows about a plugin from its registry listing entry: `mounts`, the
plugin's own route items and their resolved absolute bases (`{item: "/api/<base>"}`),
and `declaredRoutePanels`, the channels its manifest lists under
`contributions.route_panels`.

**Properties**

| Property | Type | Description |
| - | - | - |
| `declaredRoutePanels` | `readonly string[]` | — |
| `mounts` | `Readonly<Record<string, string>>` | — |

## PluginLoaderState

```ts theme={null}
interface PluginLoaderState
```

The plugin load pass's public state, mirrored for feature pages to read. It is
the shape the app shell's loader store already exposes: `status` gates when the
contributions are complete, and the error fields carry the loud failures.

**Properties**

| Property | Type | Description |
| - | - | - |
| `errors` | `Readonly<Record<string, string>>` | Plugin name → loud error message (version mismatch / load failure). |
| `loaded` | `readonly string[]` | Names of plugins whose bundle imported and registered successfully. |
| `plugins` | `readonly LoadedPlugin[]` | Identity (name + version) of every successfully-loaded plugin, parallel to `loaded`. The host reads it to attribute a contribution to its plugin — e.g. the nav provenance badge's "Plugin: name version". Empty before any plugin loads. |
| `registryError` | `string \| null` | A registry-listing failure that is NOT a 401 (surfaced loudly, never hidden). |
| `status` | `"loading" \| "ready" \| "idle"` | `idle` before the first pass, `loading` while it runs, `ready` once done. |

**Related:** [LoadedPlugin](/reference/studio-sdk/host-testing#loadedplugin)

## StaticToolDisplayNamesProvider

```ts theme={null}
function StaticToolDisplayNamesProvider(
  props: { children: ReactNode; names: Readonly<Record<string, string>>; reload?: () => void },
): FunctionComponentElement<ProviderProps<ToolDisplayNamesContextValue | null>>
```

Serve a FIXED display-name map — the test seam for a consumer that renders a tool
picker without a live fetch. `reload` defaults to a no-op; a test that exercises the
reload wiring passes a spy. Re-exported from the testing entry.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `props` | `{ children: ReactNode; names: Readonly<Record<string, string>>; reload?: () => void }` | — | — |

**Related:** [ToolDisplayNamesContextValue](/reference/studio-sdk/hooks#tooldisplaynamescontextvalue)

## \_\_resetContributions

```ts theme={null}
function __resetContributions(): void
```

Tests reset the module-level registry between cases.

## \_\_resetPluginHostState

```ts theme={null}
function __resetPluginHostState(): void
```

Tests reset the module-level host state between cases.

## contributionCovered

```ts theme={null}
function contributionCovered(
  projection: { admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string | null; principal: { display_name: string; kind: "human" | "service"; user_id: string } | null; public_resource_id: string; route_patterns: ({ open_prefix: string | null; pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ access_pattern: string; mount_url: string; slug: string; tools: string[]; transport: string })[]; tools: string[]; user_id: string },
  required: RequiredCapabilities | undefined,
): boolean
```

A full projection shows every contribution; an ABSENT requirement renders only for a
full projection (safe-by-default); a declared requirement renders when the projection
reaches at least one of its routes.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `projection` | `{ admin: boolean; agents: string[]; mintable: boolean; owner_user_id: string \| null; principal: { display_name: string; kind: "human" \| "service"; user_id: string } \| null; public_resource_id: string; route_patterns: ({ open_prefix: string \| null; pattern: string; scope_id: string })[]; routes: ({ methods: string[]; path: string })[]; scopes: string[]; sub_mcp: ({ access_pattern: string; mount_url: string; slug: string; tools: string[]; transport: string })[]; tools: string[]; user_id: string }` | — | — |
| `required` | `RequiredCapabilities \| undefined` | — | — |

**Related:** [RequiredCapabilities](/reference/studio-sdk/plugin-api#requiredcapabilities)

## deferred

```ts theme={null}
function deferred<T>(): { promise: Promise<T>; reject: (reason: unknown) => void; resolve: (value: T) => void }
```

A promise whose settlement the test controls, returned alongside its own
`resolve`/`reject`. It pins a component's loading state for assertion: hand the
unsettled `promise` to the code under test (e.g. as a mocked api call's return
value), assert the in-flight UI while it hangs, then call `resolve`/`reject` to
drive the success or failure branch and assert the settled UI. Each call
returns a fresh, independent deferred.

## flushResizeObservers

```ts theme={null}
function flushResizeObservers(): void
```

Fires every live `ResizeObserver` stub's callback for the elements it is
observing. Pair it with `setElementOverflow` to drive a component that
measures itself (`ScrollRegion` and `useProseScrollRegions` re-read
`scrollWidth`/`clientWidth` from their observer callbacks):

setElementOverflow(region, true);
flushResizeObservers();

Only meaningful once `installJsdomStubs` has installed the stub; with a real
`ResizeObserver` present (a browser environment) there is nothing to flush.

## flushResizeObserversFor

```ts theme={null}
function flushResizeObserversFor(target: Element): void
```

Delivers a resize for ONE element, to every stub observing it — the narrow
form of `flushResizeObservers`. Use it to prove which element a
component is watching: a measurement driven by a resize of a CHILD only
arrives if that child is observed, so the assertion fails the moment a
component narrows its observation to its own box.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `target` | `Element` | — | the element whose resize to deliver. |

## getContributions

```ts theme={null}
function getContributions(): PluginContributions
```

The shell reads this after loading every installed plugin bundle.

**Related:** [PluginContributions](/reference/studio-sdk/plugin-api#plugincontributions)

## getPluginHostState

```ts theme={null}
function getPluginHostState(): PluginLoaderState
```

The current mirrored host state — the snapshot `usePluginContributions` reads.

**Related:** [PluginLoaderState](/reference/studio-sdk/host-testing#pluginloaderstate)

## installJsdomStubs

```ts theme={null}
function installJsdomStubs(): void
```

jsdom omits a handful of browser APIs the Studio components reach for while a
test drives them. Installing every stub in one place keeps each feature's
`test-setup.ts` identical and lets interaction tests exercise the real
components instead of mocking them out:

* Radix primitives observe element size (`ResizeObserver`), scroll the active
  item into view, and capture the pointer while opening.
* Export/download paths create and revoke object URLs.
* File-import flows read the picked file via `Blob.text()`.
* Router scroll restoration calls `scrollTo` on navigation.

The `ResizeObserver` stub is a WORKING observer, not an inert one: it keeps a
registry of the observers still in use, delivers an entry to the callback as
each element is observed (as a real observer does for its initial
observation), and lets a test re-deliver on demand via
`flushResizeObservers`. Components that size themselves — `ScrollRegion` and
`useProseScrollRegions` — are therefore exercised for real, with
`setElementOverflow` supplying the scroll metrics jsdom cannot compute.

Each stub only fills a MISSING API, so installing the whole set everywhere is
harmless — the one exception is `window.scrollTo`, which jsdom ships as a "Not
implemented" stub that logs loudly on every navigation, so it is replaced
unconditionally. Call once from a package's Vitest `setupFiles` entry.

## loadPlugin

```ts theme={null}
function loadPlugin(
  pluginId: string,
  entry: PluginEntry,
  host: PluginLoadInputs,
): Promise<void>
```

Load one plugin: call its `register` entry with a context bound to `pluginId`,
then commit everything it staged into the global registry.

`entry` is AWAITED before commit, so a synchronous or an `async` entry is fully
done first: a post-`await` throw skips the commit (atomicity holds for async too)
and a post-`await` registration cannot slip past the batch. The seal is set after
`entry` has SETTLED, so a later registration throws loudly; registrations made
during `entry`'s synchronous body — including a microtask it enqueues then — are
still captured and committed. A `register` that throws commits nothing.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `pluginId` | `string` | — | — |
| `entry` | `PluginEntry` | — | — |
| `host` | `PluginLoadInputs` | — | — |

**Related:** [PluginEntry](/reference/studio-sdk/plugin-api#pluginentry), [PluginLoadInputs](/reference/studio-sdk/host-testing#pluginloadinputs)

## setElementOverflow

```ts theme={null}
function setElementOverflow(
  element: HTMLElement,
  overflowing: boolean,
  axis: "horizontal" | "vertical",
): void
```

Makes `element` report itself as overflowing (or not) on `axis`. jsdom runs no
layout, so `scroll*` and `client*` are both 0 and every overflow test reads as
"fits"; this shadows the prototype getters with own, configurable values so a
test can drive either state. Call it again with the opposite flag to flip the
element back.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `element` | `HTMLElement` | — | the element whose scroll metrics to fake. |
| `overflowing` | `boolean` | — | true to report content larger than the box on `axis`. |
| `axis` | `"horizontal" \| "vertical"` | `'horizontal'` | the dimension to fake: `horizontal` (width, the default) or   `vertical` (height). |

## setPluginHostState

```ts theme={null}
function setPluginHostState(state: PluginLoaderState): void
```

The host loader pushes every load-pass transition here (it stays the single
driver); every subscriber is notified so feature pages re-render off it.

**Props**

| Prop | Type | Description |
| - | - | - |
| `errors` | `Readonly<Record<string, string>>` | Plugin name → loud error message (version mismatch / load failure). |
| `loaded` | `readonly string[]` | Names of plugins whose bundle imported and registered successfully. |
| `plugins` | `readonly LoadedPlugin[]` | Identity (name + version) of every successfully-loaded plugin, parallel to `loaded`. The host reads it to attribute a contribution to its plugin — e.g. the nav provenance badge's "Plugin: name version". Empty before any plugin loads. |
| `registryError` | `string \| null` | A registry-listing failure that is NOT a 401 (surfaced loudly, never hidden). |
| `status` | `"loading" \| "ready" \| "idle"` | `idle` before the first pass, `loading` while it runs, `ready` once done. |

**Related:** [PluginLoaderState](/reference/studio-sdk/host-testing#pluginloaderstate)

## subscribePluginHost

```ts theme={null}
function subscribePluginHost(listener: () => void): () => void
```

Subscribe to host-state transitions; returns the unsubscribe function
`useSyncExternalStore` requires so a subscriber detaches on unmount.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `listener` | `() => void` | — | — |

## usePluginContributions

```ts theme={null}
function usePluginContributions(): PluginContributionsSnapshot
```

Subscribe to the plugin host state and read the committed contributions. The
status drives re-renders as the load pass advances; `contributions` is only
meaningful once `status === 'ready'` (before then the pass has committed
nothing, so callers render their non-plugin content).

**Related:** [PluginContributionsSnapshot](/reference/studio-sdk/host-testing#plugincontributionssnapshot)


# Studio SDK
Source: https://docs.tai42.ai/reference/studio-sdk/index

The generated @tai42/studio-sdk reference — the plugin contract, hooks, and design system.

The Studio SDK reference is generated from the doc comments of the public `@tai42/studio-sdk` exports — the plugin contract every Studio plugin implements, the hooks and providers each feature builds on, and the design-system components.

> **[Plugin API](/reference/studio-sdk/plugin-api)**
>
> The plugin contract a Studio plugin implements — the context, contribution types, and the compatibility gate. (23 exports)

> **[Hooks](/reference/studio-sdk/hooks)**
>
> The React hooks and providers every feature builds on — API access, theme, auth, and the interactions stream. (39 exports)

> **[Navigation](/reference/studio-sdk/navigation)**
>
> The shell⇄feature route-token contract — the navigation provider, links, and resolution hooks. (20 exports)

> **[Components](/reference/studio-sdk/components)**
>
> The design-system components — inputs, layout, tables, pickers, and disclosure primitives. (254 exports)

> **[Schema forms](/reference/studio-sdk/schema-forms)**
>
> The schema-driven form renderer and the JSON Schema helpers it is built on. (28 exports)

> **[MCP widgets](/reference/studio-sdk/mcp-widgets)**
>
> The MCP-context widgets — elicitation forms and structured-output rendering. (4 exports)

> **[Utilities](/reference/studio-sdk/utilities)**
>
> Shared helpers and re-exported types the SDK exposes. (85 exports)

> **[Host & testing](/reference/studio-sdk/host-testing)**
>
> The host-only registry API (loadPlugin / getContributions) and the test-only reset. (19 exports)


# MCP widgets
Source: https://docs.tai42.ai/reference/studio-sdk/mcp-widgets

The MCP-context widgets — elicitation forms and structured-output rendering.

The MCP-context widgets — elicitation forms and structured-output rendering.

## ElicitationForm

```ts theme={null}
function ElicitationForm(props: ElicitationFormProps): ReactNode
```

Render the elicit message + a schema-driven answer form. On submit the answer
is validated against the schema; on success `onSubmit` receives the typed
value, otherwise the per-field errors surface and nothing is emitted.

**Props**

| Prop | Type | Description |
| - | - | - |
| `busy?` | `boolean` | Disables submission while an answer is in flight. |
| `message` | `string` | The elicit request's human-readable message. |
| `onCancel?` | `() => void` | Optional cancel affordance (UI only; not an MCP decline). |
| `onSubmit` | `(answer: unknown) => void` | Called with the validated answer when the human submits. |
| `schema` | `JsonSchema` | The elicit `requestedSchema` — the answer's form schema. |
| `submitLabel?` | `string` | — |

**Related:** [ElicitationFormProps](/reference/studio-sdk/mcp-widgets#elicitationformprops)

## ElicitationFormProps

```ts theme={null}
interface ElicitationFormProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `busy?` | `boolean` | Disables submission while an answer is in flight. |
| `message` | `string` | The elicit request's human-readable message. |
| `onCancel?` | `() => void` | Optional cancel affordance (UI only; not an MCP decline). |
| `onSubmit` | `(answer: unknown) => void` | Called with the validated answer when the human submits. |
| `schema` | `JsonSchema` | The elicit `requestedSchema` — the answer's form schema. |
| `submitLabel?` | `string` | — |

**Related:** [JsonSchema](/reference/studio-sdk/schema-forms#jsonschema)

## StructuredOutput

```ts theme={null}
function StructuredOutput(props: StructuredOutputProps): ReactNode
```

Render `content` through `schema`. An object schema drives a labeled,
ordered field list (each value shown with a `JsonTree`); anything else — no
schema, a non-object schema, or content that is not a matching object —
renders the raw content through a single `JsonTree`.

**Props**

| Prop | Type | Description |
| - | - | - |
| `content` | `unknown` | The `structured_content` the tool returned. |
| `schema?` | `JsonSchema` | The tool's declared MCP output schema, if any. |

**Related:** [StructuredOutputProps](/reference/studio-sdk/mcp-widgets#structuredoutputprops)

## StructuredOutputProps

```ts theme={null}
interface StructuredOutputProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `content` | `unknown` | The `structured_content` the tool returned. |
| `schema?` | `JsonSchema` | The tool's declared MCP output schema, if any. |

**Related:** [JsonSchema](/reference/studio-sdk/schema-forms#jsonschema)


# Navigation
Source: https://docs.tai42.ai/reference/studio-sdk/navigation

The shell⇄feature route-token contract — the navigation provider, links, and resolution hooks.

The shell⇄feature route-token contract — the navigation provider, links, and resolution hooks.

## AppLink

```ts theme={null}
function AppLink<T extends keyof RouteSearchByToken>(props: AppLinkProps<T>): ReactNode
```

A real anchor (so middle-click / open-in-new-tab keep working) that drives a
client-side transition on plain left-click. Modified clicks (new tab/window,
download) fall through to the browser's default handling.

**Props**

| Prop | Type | Description |
| - | - | - |
| `aria-current?` | `boolean \| "time" \| "true" \| "false" \| "page" \| "step" \| "location" \| "date"` | — |
| `aria-label?` | `string` | — |
| `children` | `ReactNode` | — |
| `className?` | `string` | — |
| `search?` | `RouteSearch<T>` | — |
| `style?` | `CSSProperties` | Inline styles for the anchor. |
| `title?` | `string` | Native tooltip text (also a sensible non-AT hover hint). |
| `to` | `T` | — |

**Related:** [AppLinkProps](/reference/studio-sdk/navigation#applinkprops)

## AppLinkProps

```ts theme={null}
interface AppLinkProps<T extends RouteToken>
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `aria-current?` | `boolean \| "time" \| "true" \| "false" \| "page" \| "step" \| "location" \| "date"` | — |
| `aria-label?` | `string` | — |
| `children` | `ReactNode` | — |
| `className?` | `string` | — |
| `search?` | `RouteSearch<T>` | — |
| `style?` | `CSSProperties` | Inline styles for the anchor. |
| `title?` | `string` | Native tooltip text (also a sensible non-AT hover hint). |
| `to` | `T` | — |

**Related:** [RouteSearch](/reference/studio-sdk/navigation#routesearch)

## NavigateOptions

```ts theme={null}
interface NavigateOptions
```

How a token navigation enters session history.

The default is a PUSH: a move the reader made, which Back must be able to undo.
`replace` overwrites the current entry instead, and is for a transition the
reader did NOT make — a page rewriting an unrenderable URL of its own accord.
Pushing such a rewrite leaves the URL it rewrote sitting behind Back, where
pressing Back rewrites it again and pushes again: a page no Back can leave.

**Properties**

| Property | Type | Description |
| - | - | - |
| `replace?` | `boolean` | Overwrite the current history entry instead of pushing a new one. |

## NavigationContextValue

```ts theme={null}
interface NavigationContextValue
```

The runtime navigation surface the shell provides through
`NavigationProvider`. `navigate` performs a client-side transition, by
default pushing a history entry — see `NavigateOptions` for the third
argument that replaces one instead. `resolvePath` produces the href a link
should point at (so an AppLink is a real anchor — middle-click /
open-in-new-tab work — while still driving a client-side transition on plain
click).

`navigatePlugin`/`resolvePluginPath` are the plugin-page twins: they target a
runtime plugin path (`/plugins/{pluginId}/{pagePath}` plus an optional validated
sub-path `params` and `search`), NOT a route token — `routes.ts` never learns
plugin paths. Plugins reach these two via the `usePluginNavigation` hook.

**Properties**

| Property | Type | Description |
| - | - | - |
| `navigate` | `<T extends keyof RouteSearchByToken>(token: T, search?: RouteSearch<T>, options?: NavigateOptions) => void` | — |
| `navigatePlugin` | `(pluginId: string, pagePath: string, params?: string, search?: PluginSearch) => void` | — |
| `navigatePluginWithOptions?` | `(pluginId: string, pagePath: string, params?: string, search?: PluginSearch, options?: PluginNavigateOptions) => void` | ADDITIVE plugin-page navigation that also carries per-history-entry PluginNavigateOptions. OPTIONAL because a host that does not implement it leaves it undefined; plugins reach it — and require a host that provides it — through usePluginEntryNavigation, which throws loudly when it is absent. It behaves exactly like navigatePlugin for path / params / search, and in addition writes `options.state` onto the DESTINATION entry under the plugin's own namespace slot (see PluginPageProps.entryState).  It is a separate optional member rather than an extra parameter on navigatePlugin so it stays additive under the plugin-API equality gate: a new optional member does not move STUDIO\_PLUGIN\_API\_VERSION, so every existing plugin keeps loading and navigatePlugin's own signature stays stable. |
| `resolvePath` | `<T extends keyof RouteSearchByToken>(token: T, search?: RouteSearch<T>) => string` | — |
| `resolvePluginPath` | `(pluginId: string, pagePath: string, params?: string, search?: PluginSearch) => string` | — |
| `updatePluginEntryState?` | `(pluginId: string, state: unknown) => void` | ADDITIVE: replace the CURRENT history entry's per-entry state slot for `pluginId` IN PLACE (merge-preserving other plugins' slots), WITHOUT navigating — the URL, params, search, and scroll are untouched. A page uses it to checkpoint its live view state onto the entry the reader is already on, so a later back/forward or a hard reload restores it. OPTIONAL for the same additive reason as navigatePluginWithOptions; reached through usePluginEntryNavigation. |

**Related:** [NavigateOptions](/reference/studio-sdk/navigation#navigateoptions), [PluginNavigateOptions](/reference/studio-sdk/navigation#pluginnavigateoptions), [PluginSearch](/reference/studio-sdk/navigation#pluginsearch), [RouteSearch](/reference/studio-sdk/navigation#routesearch), [RouteSearchByToken](/reference/studio-sdk/navigation#routesearchbytoken)

## NavigationGuardHandler

```ts theme={null}
type NavigationGuardHandler = () => boolean | Promise<boolean>
```

A navigation guard's decision function, run while armed before any SDK-controlled
navigation commits (`navigate`,
`navigatePlugin`, or a browser back/forward). Returns
`true` to proceed, `false` to veto; a promise lets it await a confirm dialog.

Guards compose — navigation proceeds only if every armed guard allows, and the first
veto blocks (at most one dialog). A full-page unload can't await, so it is covered by
a `beforeunload` prompt independent of this handler.

## NavigationProvider

```ts theme={null}
function NavigationProvider(
  props: { children: ReactNode; value: NavigationContextValue },
): ReactNode
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `props` | `{ children: ReactNode; value: NavigationContextValue }` | — | — |

**Related:** [NavigationContextValue](/reference/studio-sdk/navigation#navigationcontextvalue)

## PageProps

```ts theme={null}
interface PageProps<T extends RouteToken>
```

Props the shell passes to a feature's page component: the route's typed search
parameters. Features type their exported page as `PageProps<'tools'>` and read
`search` — they receive route state as data, never by importing the router.

**Properties**

| Property | Type | Description |
| - | - | - |
| `search` | `RouteSearch<T>` | — |

**Related:** [RouteSearch](/reference/studio-sdk/navigation#routesearch)

## PluginNavigateOptions

```ts theme={null}
interface PluginNavigateOptions
```

Per-navigation options for `navigatePluginWithOptions`.

`replace` mirrors `replace`: overwrite the current history
entry instead of pushing a new one (a page rewriting its own unrenderable URL).

`state` is an opaque, per-history-ENTRY bag the host stores ON the destination
history entry, namespaced to the navigating plugin, and hands the page back as
`entryState`. It survives back/forward traversal AND a hard
reload — the browser persists `history.state` across a document load, verified in
a real browser against the router's pinned major before this channel was built.
Two hard rules bind the value:

* JSON-ROUND-TRIP: it is serialized into `history.state`, so it must survive
  structured-clone / JSON semantics — plain data only, no functions, DOM nodes,
  or class instances. The page reads back a structural COPY, never the same
  reference it wrote.
* SIZE: `history.state` is browser-bounded (Firefox caps a serialized entry at
  16 MiB; others higher). Keep a slot SMALL — a soft cap of \~32 KB — and store
  only view state (a selection, a scroll anchor, a draft id), never bulk data.
  Oversized state risks a browser-thrown navigation; the host does not police
  the cap, so the discipline is the plugin's.

**Properties**

| Property | Type | Description |
| - | - | - |
| `replace?` | `boolean` | Overwrite the current history entry instead of pushing a new one. |
| `state?` | `unknown` | Opaque, JSON-round-trippable per-entry state (soft cap \~32 KB); see the type doc. |

## PluginSearch

```ts theme={null}
type PluginSearch = Record<string, unknown>
```

A plugin page's deep-link search object. Plugin paths are RUNTIME contributions
outside the compile-time `RouteToken` map, so their search is an open bag of
serializable values (the page's own `PluginPageParamsSchema` validates it);
this is deliberately NOT a `RouteSearch`.

## RouteSearch

```ts theme={null}
type RouteSearch<T extends RouteToken> = RouteSearchByToken[T]
```

The search parameters a given route token accepts.

**Related:** [RouteSearchByToken](/reference/studio-sdk/navigation#routesearchbytoken)

## RouteSearchByToken

```ts theme={null}
interface RouteSearchByToken
```

Every top-level route the shell owns, mapped to its typed search parameters.
A route with no parameters maps to the empty object. Detail views are driven
by a search parameter (e.g. the selected tool / connection), keeping the route
map flat — one entry per feature surface, matching the shell route map.

**Properties**

| Property | Type | Description |
| - | - | - |
| `agents` | `Record<string, never>` | — |
| `connectors` | `{ connection?: string }` | — |
| `conversations` | `{ address?: string; q?: string; route?: string; status?: "superseded" \| "failed" \| "sending" \| "silent" \| "merged" \| "accepted" \| "pending_delivery" \| "provisional" \| "delivered" \| "shed" \| "outcome_unknown"; thread?: string }` | — |
| `extensions` | `Record<string, never>` | — |
| `hooks` | `Record<string, never>` | — |
| `interactions` | `Record<string, never>` | — |
| `login` | `Record<string, never>` | — |
| `manifest` | `Record<string, never>` | — |
| `marketplace` | `{ category?: string; kind?: string; plugin?: string; q?: string; sort?: "name" \| "downloads" \| "updated" \| "relevance"; tab?: "browse" \| "installed"; tags?: string[] }` | — |
| `members` | `Record<string, never>` | — |
| `notifications` | `Record<string, never>` | — |
| `observability` | `{ dir?: "asc" \| "desc"; from?: string; maxCost?: number; maxLatencyMs?: number; maxTokens?: number; minCost?: number; minLatencyMs?: number; minTokens?: number; sort?: "createdAt" \| "cost" \| "latencyMs" \| "totalTokens"; status?: "error" \| "success"; tab?: "dashboard" \| "tracing"; tags?: string[]; to?: string; trace?: string }` | — |
| `presets` | `{ preset?: string }` | — |
| `scheduling` | `Record<string, never>` | — |
| `servedEndpoints` | `Record<string, never>` | — |
| `settings` | `Record<string, never>` | — |
| `states` | `{ state?: string; subject?: string; tab?: "declaration" \| "templates" \| "records" \| "consumers"; target?: string; template?: string }` | — |
| `storage` | `{ q?: string }` | — |
| `system` | `Record<string, never>` | — |
| `templates` | `{ q?: string; template?: string }` | — |
| `tools` | `{ q?: string; tags?: string[]; tool?: string }` | — |

## RouteToken

```ts theme={null}
type RouteToken = keyof RouteSearchByToken
```

An opaque, typed handle to a shell route.

**Related:** [RouteSearchByToken](/reference/studio-sdk/navigation#routesearchbytoken)

## SearchCommitParams

```ts theme={null}
interface SearchCommitParams<T extends RouteToken>
```

The inputs a page hands `useSearchCommit`: the route token the commit
targets, the container whose delegated Enter/blur commits, the search input's
accessible name (the delegation keys the input on it), the committed value now in
the URL, the live draft, the page's composer of the full search object from the
next query (`undefined` when the box is empty), and the loud message thrown if the
container ref never attaches.

**Properties**

| Property | Type | Description |
| - | - | - |
| `buildSearch` | `(query: string \| undefined) => RouteSearch<T>` | — |
| `committedValue` | `string` | — |
| `containerMissingError` | `string` | — |
| `containerRef` | `RefObject<HTMLElement \| null>` | — |
| `draft` | `string` | — |
| `searchLabel` | `string` | — |
| `token` | `T` | — |

**Related:** [RouteSearch](/reference/studio-sdk/navigation#routesearch)

## useAppNavigate

```ts theme={null}
function useAppNavigate(): <T extends keyof RouteSearchByToken>(token: T, search?: RouteSearch<T>, options?: NavigateOptions) => void
```

Imperative navigation to a shell route token with its typed search params.

**Related:** [NavigateOptions](/reference/studio-sdk/navigation#navigateoptions), [RouteSearch](/reference/studio-sdk/navigation#routesearch), [RouteSearchByToken](/reference/studio-sdk/navigation#routesearchbytoken)

## useNavigationGate

```ts theme={null}
function useNavigationGate(): (href: string) => Promise<boolean>
```

Consult the armed navigation guards before a transition the shell drives itself
(a chrome link whose target is outside the route-token map). Resolves `true` when
the navigation may proceed. Token and plugin navigations already run this gate
inside `NavigationProvider`; this is the escape hatch for the shell's own
raw-path links, without which such a link would bypass every armed guard.

## useNavigationGuard

```ts theme={null}
function useNavigationGuard(when: boolean, handler: NavigationGuardHandler): void
```

Block navigation away from the current page while `when` is true. `handler` is
consulted before any SDK-controlled navigation commits — a route-token navigate,
a plugin navigate, or a browser back/forward — and the navigation proceeds only if
it resolves `true`; a promise lets the handler drive a confirm dialog. A full-page
unload (tab close / refresh) is additionally covered by a native `beforeunload`
prompt that fires whenever any guard is armed.

Guards compose against the provider's shared registry: a feature and a plugin page
may each arm one, and any veto blocks.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `when` | `boolean` | — | — |
| `handler` | `NavigationGuardHandler` | — | — |

**Related:** [NavigationGuardHandler](/reference/studio-sdk/navigation#navigationguardhandler)

## usePluginEntryNavigation

```ts theme={null}
function usePluginEntryNavigation(): { navigatePluginWithOptions: (pluginId: string, pagePath: string, params?: string, search?: PluginSearch, options?: PluginNavigateOptions) => void; updatePluginEntryState: (pluginId: string, state: unknown) => void }
```

Plugin-page navigation WITH the per-history-entry state channel:
`navigatePluginWithOptions` navigates and writes a per-entry state slot, and
`updatePluginEntryState` checkpoints the CURRENT entry's slot in place (no
navigation). Both require a host that provides the channel; on an OLDER host that
predates it, this hook THROWS a loud, descriptive error rather than silently
degrading — the plugin then knows to fall back or the deployment knows to update the
host. A plugin that only navigates without carrying state should keep using
`usePluginNavigation`, which every host supports.

**Related:** [PluginNavigateOptions](/reference/studio-sdk/navigation#pluginnavigateoptions), [PluginSearch](/reference/studio-sdk/navigation#pluginsearch)

## usePluginNavigation

```ts theme={null}
function usePluginNavigation(): Pick<NavigationContextValue, "navigatePlugin" | "resolvePluginPath">
```

Plugin-page navigation: `navigatePlugin` drives a client-side transition to a
runtime plugin path, `resolvePluginPath` yields its href. These are the ONLY
navigation methods a plugin page uses to reach its own deep-linkable sub-paths —
the token-typed `useAppNavigate`/`useResolvePath` address the shell's
compile-time routes and know nothing of plugin paths.

**Related:** [NavigationContextValue](/reference/studio-sdk/navigation#navigationcontextvalue)

## useResolvePath

```ts theme={null}
function useResolvePath(): <T extends keyof RouteSearchByToken>(token: T, search?: RouteSearch<T>) => string
```

Resolve a token + search to the href the shell would route to.

**Related:** [RouteSearch](/reference/studio-sdk/navigation#routesearch), [RouteSearchByToken](/reference/studio-sdk/navigation#routesearchbytoken)

## useSearchCommit

```ts theme={null}
function useSearchCommit<T extends keyof RouteSearchByToken>(
  props: SearchCommitParams<T>,
): void
```

The shared commit behavior for a filter box that writes its text into a route-token
search param. The SDK search input is controlled (value/onChange only), so the URL
commit is delegated on the CONTAINER: Enter or an edited blur of the search box
writes the URL. The listeners bind once — the latest draft and committed value are
read from a ref, never re-bound per keystroke.

A commit REPLACES the current history entry rather than pushing: a filter change
refines the current view, not a place Back should step back through one
keystroke-commit at a time. A cleared box commits `undefined` so the URL and box
cannot drift. A redundant commit (the draft already the committed value, trimmed
both sides, so a padded deep-link never self-commits without a real edit) writes
nothing.

**Props**

| Prop | Type | Description |
| - | - | - |
| `buildSearch` | `(query: string \| undefined) => RouteSearch<T>` | — |
| `committedValue` | `string` | — |
| `containerMissingError` | `string` | — |
| `containerRef` | `RefObject<HTMLElement \| null>` | — |
| `draft` | `string` | — |
| `searchLabel` | `string` | — |
| `token` | `T` | — |

**Related:** [SearchCommitParams](/reference/studio-sdk/navigation#searchcommitparams)


# Plugin API
Source: https://docs.tai42.ai/reference/studio-sdk/plugin-api

The plugin contract a Studio plugin implements — the context, contribution types, and the compatibility gate.

The plugin contract a Studio plugin implements — the context, contribution types, and the compatibility gate.

## ChannelConversationRoute

```ts theme={null}
type ChannelConversationRoute = Extract<ConversationRouteView, { door: "channel" }>
```

A conversation route row as `GET /api/conversations` lists it, on the `channel` door.

## NavEntryContribution

```ts theme={null}
interface NavEntryContribution
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `icon?` | `ComponentType` | Optional icon rendered before the title. It must be a square inline SVG that fills its box and draws with `currentColor`; the host constrains the slot, rendering it inside a fixed 1em box, `aria-hidden` (the accessible name is `title`), with the color inherited from the link. Its bytes live inside the plugin bundle, so no external fetch and no CSP change. Absent icon renders a text-only entry, exactly like the core nav. |
| `order?` | `number` | Optional sort weight WITHIN the entry's section (whether a core section or the shared "Plugins" one): entries render in ascending `order`, and every entry that omits it sorts AFTER the ordered ones, in registration order. Two entries with the same `order` keep registration order (a stable sort). Additive — an older bundle omits it and stays on the same plugin API version. |
| `path` | `string` | Path of a page THIS plugin registers. The nav entry links to `/plugins/{pluginId}/{path}`, so it must match a PageContribution `path` of the same plugin — the registry rejects a nav entry with no page. |
| `requiredCapabilities?` | `RequiredCapabilities` | Capability gate (see RequiredCapabilities); absent ⇒ full-only. |
| `section?` | `NavEntrySection` | Optional target sidebar section (see NavEntrySection); absent ⇒ the shared "Plugins" section. Additive — an older bundle omits it and stays on the same plugin API version. |
| `title` | `string` | — |

**Related:** [NavEntrySection](/reference/studio-sdk/plugin-api#naventrysection), [RequiredCapabilities](/reference/studio-sdk/plugin-api#requiredcapabilities)

## NavEntrySection

```ts theme={null}
type NavEntrySection = "Capabilities" | "Connections" | "Triggers" | "Activity" | "Administration"
```

The sidebar section a nav entry renders in. A named core section groups the
entry there, after that section's core rows. An absent field or any value that
is not a live core section renders the entry in the shared "Plugins" section that
follows the core sections (alongside every other undeclared plugin entry),
placed after the core sections. The shell tolerates an unknown value at runtime
(a bundle newer than this host), falling back to that shared section, so the
field is a placement hint, never a hard contract.

## PageContribution

```ts theme={null}
interface PageContribution
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `component` | `ComponentType<PluginPageProps>` | — |
| `params?` | `PluginPageParamsSchema` | Deep-link schema (see PluginPageParamsSchema). When present the page is addressable under its `path` PREFIX, and the shell validates the sub-path remainder + search before rendering. Absent ⇒ the page matches only its exact `path` and receives no `params`/`search` (unchanged behavior). |
| `path` | `string` | URL segment under `/plugins/{pluginId}/`. |
| `requiredCapabilities?` | `RequiredCapabilities` | Capability gate (see RequiredCapabilities); absent ⇒ full-only. |
| `title` | `string` | — |

**Related:** [PluginPageParamsSchema](/reference/studio-sdk/plugin-api#pluginpageparamsschema), [PluginPageProps](/reference/studio-sdk/plugin-api#pluginpageprops), [RequiredCapabilities](/reference/studio-sdk/plugin-api#requiredcapabilities)

## PluginContext

```ts theme={null}
interface PluginContext
```

The registration surface a plugin receives in its `register(context)` entry.
Each method binds the contribution to the plugin the host is loading — the
plugin's identity is fixed by the host, not read from any ambient state — so a
contribution can never be misattributed to another plugin. Contributions are
staged and committed together once `register` settles; a `register` that throws
commits nothing. The context is SEALED once `register` settles: a call made
after that (a deferred timer, a post-resolve microtask) throws instead of
silently dropping, so every registration must happen during `register`.

**Properties**

| Property | Type | Description |
| - | - | - |
| `registerNavEntry` | `(contribution: NavEntryContribution) => void` | Register a sidebar nav entry linking to one of this plugin's pages at `/plugins/{pluginId}/{path}`. The `path` must match a page the plugin also registers (a nav entry with no page is a dead link and is rejected loudly). |
| `registerPage` | `(contribution: PageContribution) => void` | Register a full page mounted under `/plugins/{pluginId}/{path}`. |
| `registerRoutePanel` | `(contribution: RoutePanelContribution) => void` | Register a panel for the routes of one channel. The plugin's manifest must list the same channels under `contributions.route_panels`, or the plugin fails to load. |
| `registerSettingsTab` | `(contribution: SettingsTabContribution) => void` | Register a settings tab. |
| `registerToolPanel` | `(contribution: ToolPanelContribution) => void` | Register a rich run panel for a tool by name (overrides the auto-form). |
| `routeBase` | `(itemName: string) => string \| null` | The resolved absolute base of one of this plugin's route items, e.g. `/api/channels/web`, or `null` when the item has no mount on this deployment (an optional router not listed, a channel not loaded). Never throws; a feature that needs the base shows its own unavailable state for `null`. Call it during `register` and keep the value. |

**Related:** [NavEntryContribution](/reference/studio-sdk/plugin-api#naventrycontribution), [PageContribution](/reference/studio-sdk/plugin-api#pagecontribution), [RoutePanelContribution](/reference/studio-sdk/plugin-api#routepanelcontribution), [SettingsTabContribution](/reference/studio-sdk/plugin-api#settingstabcontribution), [ToolPanelContribution](/reference/studio-sdk/plugin-api#toolpanelcontribution)

## PluginContributions

```ts theme={null}
interface PluginContributions
```

Everything a single plugin bundle has registered at import time.

**Properties**

| Property | Type | Description |
| - | - | - |
| `navEntries` | `readonly RegisteredNavEntry[]` | — |
| `pages` | `readonly RegisteredPage[]` | — |
| `routePanels` | `ReadonlyMap<string, RegisteredRoutePanel>` | Route panels keyed by the channel they decorate. |
| `settingsTabs` | `readonly RegisteredSettingsTab[]` | — |
| `toolPanels` | `ReadonlyMap<string, ToolPanelContribution>` | — |

**Related:** [RegisteredNavEntry](/reference/studio-sdk/plugin-api#registerednaventry), [RegisteredPage](/reference/studio-sdk/plugin-api#registeredpage), [RegisteredRoutePanel](/reference/studio-sdk/plugin-api#registeredroutepanel), [RegisteredSettingsTab](/reference/studio-sdk/plugin-api#registeredsettingstab), [ToolPanelContribution](/reference/studio-sdk/plugin-api#toolpanelcontribution)

## PluginEntry

```ts theme={null}
type PluginEntry = (context: PluginContext) => void | Promise<void>
```

A plugin bundle's entry: the default plugin API. The host imports the bundle,
reads its `register` export, and calls it with a `PluginContext`. All
contributions flow through that context — there are no free registration
functions. The entry may be synchronous or `async`; the host awaits it before
committing, so an async entry must complete every registration before it
resolves (see the seal on `PluginContext`).

**Related:** [PluginContext](/reference/studio-sdk/plugin-api#plugincontext)

## PluginPageParamsSchema

```ts theme={null}
interface PluginPageParamsSchema
```

A page's optional deep-link schema. The shell resolves a URL to a page by
LONGEST registered `path` prefix; the remainder of the URL after the matched
prefix is handed to `parseParams`, and the raw search object to `parseSearch`.
Each parser VALIDATES and shapes its input, RAISING on anything it rejects — the
shell renders that throw as a loud error card, never a blank or partial view. A
contribution that omits the schema entirely accepts no sub-path (the pre-deep-link
behavior, unchanged). Omitting just one parser leaves that half unvalidated:
absent `parseParams` means the page still matches only its exact `path`; absent
`parseSearch` means `search` is not forwarded.

**Properties**

| Property | Type | Description |
| - | - | - |
| `parseParams?` | `(remainder: string) => Record<string, unknown>` | Validate + shape the sub-path remainder after this page's prefix; throws to reject. |
| `parseSearch?` | `(raw: Record<string, unknown>) => Record<string, unknown>` | Validate + shape the raw search object; throws to reject. |

## PluginPageProps

```ts theme={null}
interface PluginPageProps
```

Props a contributed full page receives. A page is deep-linkable: the shell mounts
it at `/plugins/{pluginId}/{path}` and, when the contribution declares a
`PluginPageParamsSchema`, forwards the VALIDATED sub-path remainder as
`params` and the VALIDATED search object as `search`. Both are OPTIONAL — a page
that declares no schema receives neither (and accepts no sub-path), so this stays
a non-breaking addition to every existing contribution and the plugin API version
does not move. Navigate between plugin pages with `usePluginNavigation`.

**Properties**

| Property | Type | Description |
| - | - | - |
| `entryState?` | `unknown` | The per-history-entry state slot the host stored for THIS plugin on the current history entry (written via `navigatePluginWithOptions` / `updatePluginEntryState` on the SDK navigation surface), or `undefined` when none was set. It survives back/forward traversal and a hard reload, because the host round-trips it through `history.state`. OPTIONAL — a page that never uses the entry-state channel receives `undefined`, so this stays a non-breaking addition and the plugin API version does not move.  FAILURE-DIVERGENCE — why there is no host-side schema for it, unlike `params` / `search`: those two come from the URL, a shareable and forgeable surface, so a bad one is a broken LINK — the host VALIDATES them against the page's PluginPageParamsSchema and renders a LOUD error card on rejection, never a half-populated view. `entryState` is different in kind: it is opaque, author-written data the host only round-trips through `history.state`, never parses and never shows a human, and the page that wrote it owns its shape. So the host delivers it RAW and the page MUST degrade GRACEFULLY on anything unexpected — treat a malformed or absent value as "no checkpoint" and fall back to defaults, never throw. That asymmetry — an error card at the host for URL surfaces, graceful raw delivery for entry state — is exactly why entry state carries no host-side schema slot. |
| `params?` | `Record<string, unknown>` | The validated sub-path remainder (present only when the page declared a schema). |
| `pluginId` | `string` | — |
| `search?` | `Record<string, unknown>` | The validated search object (present only when the page declared a schema). |

## RegisteredNavEntry

```ts theme={null}
interface RegisteredNavEntry extends NavEntryContribution
```

A nav entry as stored in the registry: the plugin's
`NavEntryContribution` plus the id of the plugin that registered it. The
`pluginId` is stamped by the registry from the identity the host passed to
`PluginEntry`, so the entry links only under its owner's
`/plugins/{pluginId}/` prefix and two plugins may register the same `path`
without colliding.

**Properties**

| Property | Type | Description |
| - | - | - |
| `icon?` | `ComponentType` | Optional icon rendered before the title. It must be a square inline SVG that fills its box and draws with `currentColor`; the host constrains the slot, rendering it inside a fixed 1em box, `aria-hidden` (the accessible name is `title`), with the color inherited from the link. Its bytes live inside the plugin bundle, so no external fetch and no CSP change. Absent icon renders a text-only entry, exactly like the core nav. |
| `order?` | `number` | Optional sort weight WITHIN the entry's section (whether a core section or the shared "Plugins" one): entries render in ascending `order`, and every entry that omits it sorts AFTER the ordered ones, in registration order. Two entries with the same `order` keep registration order (a stable sort). Additive — an older bundle omits it and stays on the same plugin API version. |
| `path` | `string` | Path of a page THIS plugin registers. The nav entry links to `/plugins/{pluginId}/{path}`, so it must match a PageContribution `path` of the same plugin — the registry rejects a nav entry with no page. |
| `pluginId` | `string` | — |
| `requiredCapabilities?` | `RequiredCapabilities` | Capability gate (see RequiredCapabilities); absent ⇒ full-only. |
| `section?` | `NavEntrySection` | Optional target sidebar section (see NavEntrySection); absent ⇒ the shared "Plugins" section. Additive — an older bundle omits it and stays on the same plugin API version. |
| `title` | `string` | — |

**Related:** [NavEntryContribution](/reference/studio-sdk/plugin-api#naventrycontribution), [NavEntrySection](/reference/studio-sdk/plugin-api#naventrysection), [RequiredCapabilities](/reference/studio-sdk/plugin-api#requiredcapabilities)

## RegisteredPage

```ts theme={null}
interface RegisteredPage extends PageContribution
```

A page as stored in the registry: the plugin's `PageContribution` plus
the id of the plugin that registered it. The `pluginId` is stamped by the
registry from the identity the host passed to `PluginEntry` — a plugin
never supplies its own id — so a page resolves only under its owner's
`/plugins/{pluginId}/` prefix and two plugins may register the same `path`
without colliding.

**Properties**

| Property | Type | Description |
| - | - | - |
| `component` | `ComponentType<PluginPageProps>` | — |
| `params?` | `PluginPageParamsSchema` | Deep-link schema (see PluginPageParamsSchema). When present the page is addressable under its `path` PREFIX, and the shell validates the sub-path remainder + search before rendering. Absent ⇒ the page matches only its exact `path` and receives no `params`/`search` (unchanged behavior). |
| `path` | `string` | URL segment under `/plugins/{pluginId}/`. |
| `pluginId` | `string` | — |
| `requiredCapabilities?` | `RequiredCapabilities` | Capability gate (see RequiredCapabilities); absent ⇒ full-only. |
| `title` | `string` | — |

**Related:** [PageContribution](/reference/studio-sdk/plugin-api#pagecontribution), [PluginPageParamsSchema](/reference/studio-sdk/plugin-api#pluginpageparamsschema), [PluginPageProps](/reference/studio-sdk/plugin-api#pluginpageprops), [RequiredCapabilities](/reference/studio-sdk/plugin-api#requiredcapabilities)

## RegisteredRoutePanel

```ts theme={null}
interface RegisteredRoutePanel extends RoutePanelContribution
```

A route panel as stored in the registry, stamped with the plugin that registered it.

**Properties**

| Property | Type | Description |
| - | - | - |
| `channel` | `string` | The channel name whose routes this panel decorates (`ConversationRouteView.channel`). |
| `component` | `ComponentType<RoutePanelProps>` | — |
| `pluginId` | `string` | — |
| `requiredCapabilities?` | `RequiredCapabilities` | Capability gate (see RequiredCapabilities); absent ⇒ full-only. |
| `title` | `string` | Names the panel region (its aria-label and the error card label). |

**Related:** [RequiredCapabilities](/reference/studio-sdk/plugin-api#requiredcapabilities), [RoutePanelContribution](/reference/studio-sdk/plugin-api#routepanelcontribution), [RoutePanelProps](/reference/studio-sdk/plugin-api#routepanelprops)

## RegisteredSettingsTab

```ts theme={null}
interface RegisteredSettingsTab extends SettingsTabContribution
```

A settings tab as stored in the registry: the plugin's
`SettingsTabContribution` plus the id of the plugin that registered it.
The `pluginId` is stamped by the registry from the identity the host passed to
`PluginEntry` — a plugin never supplies its own id — so a tab is always
attributable to its owner and two plugins may register the same tab `id`
without colliding.

**Properties**

| Property | Type | Description |
| - | - | - |
| `component` | `ComponentType<SettingsTabProps>` | — |
| `id` | `string` | — |
| `pluginId` | `string` | — |
| `requiredCapabilities?` | `RequiredCapabilities` | Capability gate (see RequiredCapabilities); absent ⇒ full-only. |
| `title` | `string` | — |

**Related:** [RequiredCapabilities](/reference/studio-sdk/plugin-api#requiredcapabilities), [SettingsTabContribution](/reference/studio-sdk/plugin-api#settingstabcontribution), [SettingsTabProps](/reference/studio-sdk/plugin-api#settingstabprops)

## RequiredCapabilities

```ts theme={null}
interface RequiredCapabilities
```

A capability requirement a contribution may declare. `routes` is a list of
route-path prefixes (anyOf semantics, the same evaluator the shell nav uses):
the contribution renders iff the caller's capability projection covers at least
one of them. ABSENT (the field is optional) means the contribution renders only
for a FULL projection — safe-by-default for every existing plugin, which never
declared a requirement. The server remains the authority; this only shapes what
the UI advertises.

**Properties**

| Property | Type | Description |
| - | - | - |
| `routes` | `readonly string[]` | — |

## RoutePanelContribution

```ts theme={null}
interface RoutePanelContribution
```

A panel the conversations drill-in renders above the thread list of every route on
one channel. One panel per channel deployment-wide.

**Properties**

| Property | Type | Description |
| - | - | - |
| `channel` | `string` | The channel name whose routes this panel decorates (`ConversationRouteView.channel`). |
| `component` | `ComponentType<RoutePanelProps>` | — |
| `requiredCapabilities?` | `RequiredCapabilities` | Capability gate (see RequiredCapabilities); absent ⇒ full-only. |
| `title` | `string` | Names the panel region (its aria-label and the error card label). |

**Related:** [RequiredCapabilities](/reference/studio-sdk/plugin-api#requiredcapabilities), [RoutePanelProps](/reference/studio-sdk/plugin-api#routepanelprops)

## RoutePanelProps

```ts theme={null}
interface RoutePanelProps
```

Props a contributed route panel receives.

**Properties**

| Property | Type | Description |
| - | - | - |
| `pluginId` | `string` | — |
| `route` | `{ callback_url: null; cancel_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; channel: string; door: "channel"; execution_key: string; execution_key_fingerprint: string; extras_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; initial_mode: "manual" \| "agent"; locale: string \| null; our_identity: string; overlap: { deliver: "all" \| "one"; running: "continue" \| "cancel"; settle_seconds: number }; reply_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; reply_texts: { error: string \| null; pairing_code: string \| null; pairing_code_invalid: string \| null; pairing_link_unavailable: string \| null; pairing_linked: string \| null; pairing_not_linked: string \| null; pairing_unlink_unavailable: string \| null; pairing_unlinked: string \| null; rejected_could_not_receive: string \| null; rejected_too_large: string \| null; rejected_unsupported_type: string \| null; slow_down: string \| null } \| null; resume_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; route_name: string; start_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; target_kind: "agent" \| "tool"; target_name: string; turns_per_hour_override: number \| null }` | The route row the panel decorates; its `channel` is the contribution's channel. |

## STUDIO\_PLUGIN\_API\_VERSION

```ts theme={null}
const STUDIO_PLUGIN_API_VERSION: 1
```

The Studio-plugin API compatibility version.

A monotonic integer bumped ONLY on a breaking change to the Studio-plugin API
OR the public prop/type surface of any DS component the SDK exports (a prop
rename/removal bumps it; genuinely internal/visual changes do not).

Gate rule: equality is correct precisely because additive changes never
bump (existing plugins keep matching) and after a break every plugin must
rebuild by design. `targeted == current` accepts; anything else rejects.

Additive evolution under this gate: a host that gains a NEW optional context
capability (a new `register*` method, a new host-side injection behavior)
keeps the same version, so every existing plugin loads unchanged. The one
asymmetry the equality gate leaves is a plugin that USES a newer capability on
an OLDER host that lacks it — and it fails loudly, by construction, not by any
negotiation machinery:

* A plugin calling a context method the host does not define throws the
  natural `context.<method> is not a function` during `register`; the loader
  catches it as that plugin's loud error card and commits nothing.
* A plugin shipping a `.css` asset to a host that does not inject stylesheets
  is served but never injected — the page renders with SDK-component styling
  only. This is the single quiet degradation the mechanism admits, and the
  authoring docs state it: stylesheet injection is a host capability, so a
  deployment pairs the Studio host with plugins built for it.

## SettingsTabContribution

```ts theme={null}
interface SettingsTabContribution
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `component` | `ComponentType<SettingsTabProps>` | — |
| `id` | `string` | — |
| `requiredCapabilities?` | `RequiredCapabilities` | Capability gate (see RequiredCapabilities); absent ⇒ full-only. |
| `title` | `string` | — |

**Related:** [RequiredCapabilities](/reference/studio-sdk/plugin-api#requiredcapabilities), [SettingsTabProps](/reference/studio-sdk/plugin-api#settingstabprops)

## SettingsTabProps

```ts theme={null}
interface SettingsTabProps
```

Props a contributed settings tab receives.

**Properties**

| Property | Type | Description |
| - | - | - |
| `pluginId` | `string` | — |

## ToolPanelContribution

```ts theme={null}
interface ToolPanelContribution
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `component` | `ComponentType<ToolPanelProps>` | — |
| `toolName` | `string` | — |

**Related:** [ToolPanelProps](/reference/studio-sdk/plugin-api#toolpanelprops)

## ToolPanelProps

```ts theme={null}
interface ToolPanelProps
```

Props a contributed tool-run panel receives (replaces the auto-form).

**Properties**

| Property | Type | Description |
| - | - | - |
| `run` | `(args: Record<string, unknown>) => Promise<unknown>` | Run the tool with arguments; resolves with the typed result or throws. |
| `schema` | `Record<string, unknown>` | The tool's JSON schema (Pydantic-emitted), for panels that introspect it. |
| `toolName` | `string` | The tool name this panel targets. |

## VersionGateResult

```ts theme={null}
interface VersionGateResult
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `ok` | `boolean` | — |
| `reason?` | `string` | — |

## checkPluginApiVersion

```ts theme={null}
function checkPluginApiVersion(targeted: number, current: number): VersionGateResult
```

Accept iff the plugin's targeted version exactly equals the host's.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `targeted` | `number` | — | — |
| `current` | `number` | `STUDIO_PLUGIN_API_VERSION` | — |

**Related:** [VersionGateResult](/reference/studio-sdk/plugin-api#versiongateresult)


# Schema forms
Source: https://docs.tai42.ai/reference/studio-sdk/schema-forms

The schema-driven form renderer and the JSON Schema helpers it is built on.

The schema-driven form renderer and the JSON Schema helpers it is built on.

## CompletionProvider

```ts theme={null}
type CompletionProvider = (argName: string, partial: string) => Promise<string[]>
```

Fetch argument-value suggestions for a string field. `argName` is the field's
path within the form (a property key at the root, a dotted path when nested);
`partial` is the value typed so far. The caller owns the source (e.g. an MCP
`completion/complete` call) — SchemaForm only routes string fields through the
completion-backed input when a provider is supplied.

## DateRangePair

```ts theme={null}
interface DateRangePair
```

A START/END pair drawable as one range control, resolved off a page's properties.

**Properties**

| Property | Type | Description |
| - | - | - |
| `endName` | `string` | — |
| `endSchema` | `JsonSchema` | — |
| `endTimeName?` | `string` | The END's `timeOf` time property among the same properties, when it has one. |
| `endTimeSchema?` | `JsonSchema` | — |
| `startName` | `string` | — |
| `startSchema` | `JsonSchema` | — |
| `startTimeName?` | `string` | The START's `timeOf` time property among the same properties, when it has one. |
| `startTimeSchema?` | `JsonSchema` | — |

**Related:** [JsonSchema](/reference/studio-sdk/schema-forms#jsonschema)

## Discriminator

```ts theme={null}
interface Discriminator
```

A Pydantic-style discriminated-union tag: which property selects the variant.

**Properties**

| Property | Type | Description |
| - | - | - |
| `mapping?` | `Readonly<Record<string, string>>` | — |
| `propertyName` | `string` | — |

## ExpressionFieldComponent

```ts theme={null}
type ExpressionFieldComponent = ComponentType<ExpressionFieldProps>
```

The expression-authoring door a host INJECTS into the form — `JqField`, which the
host imports straight from `@tai42/jq-studio`.

It is a COMPONENT, rendered as an element, never called as a function: the door
owns hooks and state (editor open, worker handle), which only survive as its own
element identity. A host may inject a `lazy` door to keep the jq subgraph in a
split chunk — the form mounts it inside a Suspense boundary that paints the
resting shell while that chunk resolves.

**Related:** [ExpressionFieldProps](/reference/studio-sdk/schema-forms#expressionfieldprops)

## ExpressionFieldContext

```ts theme={null}
const ExpressionFieldContext: Context<ExpressionFieldComponent | undefined>
```

The ambient door for the whole form. Absent (the default), an
expression-annotated field renders the PLAIN string input, byte-identically to
an unannotated one — the jq authoring door is opt-in, because the dynamic import
that would fetch it on demand still EMITS its chunks, worker, and wasm into
every consumer that bundles the SDK.

A host wires it ONCE above its tree (`SchemaEditor`'s preview and
`ElicitationForm` render forms a caller does not own the props of, and a plugin
page renders its own); the form's own `expressionField` prop overrides it for a
single form.

**Related:** [ExpressionFieldComponent](/reference/studio-sdk/schema-forms#expressionfieldcomponent)

## ExpressionFieldProps

```ts theme={null}
interface ExpressionFieldProps
```

Exactly the props the form hands an injected expression field — no more, so any
expression editor can satisfy the contract, and no less, so the form is free to
pass all of them. The label/description/error slots are the door's own chrome:
an expression field brings its a11y-linked label and helper slots, so the form
does NOT wrap it in the usual `Field`.

**Properties**

| Property | Type | Description |
| - | - | - |
| `description?` | `ReactNode` | — |
| `error?` | `ReactNode` | — |
| `label` | `string` | — |
| `multiline?` | `boolean` | Render a multiline resting control; the form always asks for one. |
| `onChange` | `(value: string) => void` | — |
| `shape?` | `ExpressionInputShape` | — |
| `value` | `string` | — |

**Related:** [ExpressionInputShape](/reference/studio-sdk/schema-forms#expressioninputshape)

## ExpressionInputKey

```ts theme={null}
interface ExpressionInputKey
```

One top-level key of the expression's input document, with a one-line gloss.

**Properties**

| Property | Type | Description |
| - | - | - |
| `gloss` | `string` | — |
| `name` | `string` | — |

## ExpressionInputShape

```ts theme={null}
interface ExpressionInputShape
```

What `.` IS for an expression-annotated field, as the form hands it to the
injected door. Built by the renderer from the schema's `x-tai42-expression`
annotation.

Like the annotation type it is built from, this MIRRORS jq-studio's input-shape
descriptor without importing it: the schema-form tree names no jq type, in code
OR in its declarations, which is what keeps a consumer that never injects a door
free of the jq subgraph. `JqField` satisfies it structurally; a test pins that.

**Properties**

| Property | Type | Description |
| - | - | - |
| `blurb` | `string` | One sentence: what `.` is in this field. |
| `caveats?` | `readonly string[]` | Per-field caveats. |
| `id` | `string` | Stable, host-namespaced id, opaque to the door (memoisation/telemetry). |
| `keys` | `readonly ExpressionInputKey[]` | The top-level keys of `.`, each with a one-liner. |
| `label` | `string` | Short chip label — what `.` is here, e.g. "node envelope". |
| `returns` | `string` | What the expression must RETURN, e.g. "true or false". |
| `sample?` | `unknown` | A static skeleton of `.` for the door's test surface. |
| `variables?` | `readonly ExpressionInputVariable[]` | The named variables the expression reads as `$name` beside `.`; omitted when  the field declares none. |

**Related:** [ExpressionInputKey](/reference/studio-sdk/schema-forms#expressioninputkey)

## FieldWords

```ts theme={null}
interface FieldWords
```

A form field's own words, keyed by the root object's property name in a form's
`fieldWording`. Every member is optional; an unset one draws the SDK's own word.

* `choiceLabel`: the placeholder of the field's `enum` select (in place of `Select…`).
* `invalid`: the sentence that replaces every shape error on the field and anything
  inside it (a format, pattern, length, bound, type or item error).
* `required`: the sentence shown when the field's required value is missing, at the
  field or anywhere inside it (in place of `"<name>" is required`).
* `addItem` / `removeItem` / `itemLabel` / `noItems`: a list field's add button, each
  item's remove button, each item's heading (its `{n}` token takes the item's number),
  and the line shown while the list is empty.

**Properties**

| Property | Type | Description |
| - | - | - |
| `addItem?` | `string` | — |
| `choiceLabel?` | `string` | — |
| `invalid?` | `string` | — |
| `itemLabel?` | `string` | — |
| `noItems?` | `string` | — |
| `removeItem?` | `string` | — |
| `required?` | `string` | — |

## FormControl

```ts theme={null}
type FormControl = "chips" | "textarea"
```

The CONTROL a surface draws for a property in place of the default for the
property's shape. `chips` draws a choice (a `string` with an `enum`, or an
`array` of such strings) as a tap-to-select chip grid instead of the
radio/select or checkbox group. `textarea` draws a `string` as a multi-line
text control instead of a single-line box. It changes what is DRAWN, never what
is accepted — the value and its validation stay the property's own.

## FormInputMode

```ts theme={null}
type FormInputMode = "text" | "numeric" | "decimal" | "tel" | "email" | "url"
```

The input KIND a `string` field collects, drawn as the matching keyboard or
native control. The vocabulary is the HTML `inputmode`/control naming of the
concept: `numeric`/`decimal` set a text box's keyboard hint; `tel`/`email`/`url`
select the matching native control. It draws, it does not validate.

## JsonSchema

```ts theme={null}
interface JsonSchema
```

A structural JSON Schema node. All keys optional; the index signature keeps
the type permissive so an unrecognized keyword is never a type error — it is a
runtime classification concern the renderer handles.

**Properties**

| Property | Type | Description |
| - | - | - |
| `$defs?` | `Readonly<Record<string, JsonSchema>>` | — |
| `$ref?` | `string` | — |
| `additionalProperties?` | `boolean \| JsonSchema` | — |
| `allOf?` | `readonly JsonSchema[]` | — |
| `anyOf?` | `readonly JsonSchema[]` | — |
| `const?` | `unknown` | — |
| `contentEncoding?` | `string` | Media annotations (see the `SchemaForm` module). `contentEncoding: "base64"` together with `contentMediaType` (or `format: "data-url"`) opts a string field into the upload control; `contentMaxBytes` pins a per-field size cap.  `contentMaxBytes` is a NONSTANDARD JSON-Schema extension keyword — a standard JSON-Schema validator ignores it. The client-side caps it drives (see the `media` module) are UX guards, NOT a security boundary: the SERVER MUST independently validate the decoded size of any uploaded content. |
| `contentMaxBytes?` | `number` | — |
| `contentMediaType?` | `string` | — |
| `control?` | `FormControl` | The CONTROL to draw for this property in place of its shape's default — a platform keyword (see FormControl). `chips` draws a `string`-with-`enum` or an `array` of such strings as a chip grid; `textarea` draws a `string` as a multi-line text control. It DRAWS, it does not validate — the answer door still enforces the property's `type`, `enum`, `maxLength` and the rest. A value outside the set is read as absent (the server ask door is the authority that refuses it). |
| `default?` | `unknown` | — |
| `definitions?` | `Readonly<Record<string, JsonSchema>>` | — |
| `description?` | `string` | — |
| `discriminator?` | `Discriminator` | — |
| `enum?` | `readonly unknown[]` | — |
| `format?` | `string` | — |
| `inputMode?` | `FormInputMode` | The input KIND a `string` field collects — a platform keyword (see FormInputMode). The renderer draws the matching keyboard or native control: `numeric`/`decimal` a text box with that keyboard hint (the value stays the typed string, so `"007"` keeps its leading zeros), `tel`/`email`/`url` the matching native control, `text` or absent a plain text box. It DRAWS, it does not validate — the answer door still enforces `type`, `pattern` and `format`. When present it OUTRANKS `format` for the control. A value outside the set is read as absent (the server ask door is the authority that refuses it). |
| `items?` | `JsonSchema` | — |
| `maxDate?` | `string` | — |
| `maxDays?` | `number` | — |
| `maxItems?` | `number` | — |
| `maxLength?` | `number` | — |
| `maximum?` | `number` | — |
| `minDate?` | `string` | Platform date-constraint keys on a `string`/`date` (or `date-time`) property. They are NOT the JSON-Schema numeric keywords (which are inert on a string): `minDate`/ `maxDate` are inclusive `YYYY-MM-DD` bounds, `unavailableDates` is a list of `YYYY-MM-DD` days to exclude. A date RANGE is TWO ordinary date fields: the END field names its start field with `rangeStart` and carries the inclusive span in `minDays`/`maxDays`; nothing is recombined. All optional; absent = an unconstrained date. The native control enforces what it can (min/max) and the validator enforces the rest, mirroring the server. |
| `minDays?` | `number` | — |
| `minItems?` | `number` | — |
| `minLength?` | `number` | — |
| `minimum?` | `number` | — |
| `oneOf?` | `readonly JsonSchema[]` | — |
| `pattern?` | `string` | — |
| `properties?` | `Readonly<Record<string, JsonSchema>>` | — |
| `rangeStart?` | `string` | — |
| `required?` | `readonly string[]` | — |
| `timeOf?` | `string` | On a `string`/`format: time` property: the name of the range-end `date` property this is the time of. The time draws right after its date (inside the range group when the pair merges), and two ends on the same date are then ordered by their times. Absent = a time field of its own. |
| `title?` | `string` | — |
| `type?` | `JsonSchemaType \| readonly JsonSchemaType[]` | — |
| `unavailableDates?` | `readonly string[]` | — |
| `visibleWhen?` | `VisibleWhen` | A declarative visibility predicate on a property: the field shows only when the predicate holds against the current form values. Static form description evaluated by the renderer (never a consumer reaction); a hidden field is not rendered and not validated. Absent = always visible. See VisibleWhen. |

**Related:** [Discriminator](/reference/studio-sdk/schema-forms#discriminator), [FormControl](/reference/studio-sdk/schema-forms#formcontrol), [FormInputMode](/reference/studio-sdk/schema-forms#forminputmode), [JsonSchemaType](/reference/studio-sdk/schema-forms#jsonschematype)

## JsonSchemaType

```ts theme={null}
type JsonSchemaType = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null"
```

The JSON-Schema `type` keyword values Pydantic emits.

## RecordEntryContext

```ts theme={null}
interface RecordEntryContext
```

One record entry, handed to a host-supplied value renderer.

**Properties**

| Property | Type | Description |
| - | - | - |
| `defaultField` | `ReactNode` | The default value editor the record field would render for this entry. |
| `keyName` | `string` | The entry's current key (may be blank/duplicate while the user edits). |
| `onChange` | `(value: unknown) => void` | — |
| `path` | `string` | The entry value's form path (dotted from the form root). |
| `value` | `unknown` | — |
| `valueSchema` | `JsonSchema` | The entry value schema, as written (the renderer resolves any `$ref`). |

**Related:** [JsonSchema](/reference/studio-sdk/schema-forms#jsonschema)

## RecordEntryRenderer

```ts theme={null}
type RecordEntryRenderer = (entry: RecordEntryContext) => ReactNode
```

A host-supplied per-entry value renderer for `record` fields — the injection
point a masked/secret editor (or any other value affordance) mounts through.
It returns the node to render in the entry's value slot; returning
`entry.defaultField` falls back to the built-in editor. Absent (the default),
every entry renders its `defaultField`.

**Related:** [RecordEntryContext](/reference/studio-sdk/schema-forms#recordentrycontext)

## RecordEntryRendererContext

```ts theme={null}
const RecordEntryRendererContext: Context<RecordEntryRenderer | undefined>
```

**Related:** [RecordEntryRenderer](/reference/studio-sdk/schema-forms#recordentryrenderer)

## SchemaForm

```ts theme={null}
function SchemaForm(props: SchemaFormProps): ReactNode
```

Render a controlled form for `schema`. The root is usually an object (a tool's
input schema); a scalar/array/union root renders as a single field group.

**Props**

| Prop | Type | Description |
| - | - | - |
| `completionProvider?` | `CompletionProvider` | Optional. When supplied, every string field renders through the completion-backed input (argument autocomplete); when omitted, string fields render as a plain text input — the default, unchanged behaviour. |
| `errors?` | `Readonly<Record<string, string>>` | — |
| `expressionField?` | `ExpressionFieldComponent` | Optional. The expression-authoring door for `x-tai42-expression` fields — `JqField` from `@tai42/jq-studio`, which the host imports directly and passes here (see the module doc-comment). Omitted, the enclosing ExpressionFieldContext supplies it; absent both, an annotated field renders the plain string input. |
| `fieldWording?` | `Readonly<Record<string, FieldWords>>` | Optional. Per-field words, keyed by the root object's property name. A top-level `enum` field that draws as a select shows its entry's `choiceLabel` as the select placeholder (in place of the default `Select…`); a top-level list field draws its entry's `addItem`, `removeItem`, `itemLabel` (`{n}` the item's number) and `noItems` (in place of `Add item`, `Remove`, `Item {n}` and `No items`). Nested fields and other controls are unaffected, and a field with no entry draws the defaults. The entry's `invalid` and `required` sentences are not read here: pass the same record to `validateAgainstSchema` as `fieldWording`, and the errors it returns carry them. |
| `idPrefix?` | `string` | — |
| `maxUploadBytes?` | `number` | Optional. Default byte cap for media-upload fields (see the module doc-comment). A field's own `contentMaxBytes` annotation overrides it; absent both, DEFAULT\_MAX\_UPLOAD\_BYTES applies. |
| `onChange` | `(value: unknown) => void` | — |
| `schema` | `JsonSchema` | — |
| `value` | `unknown` | — |

**Related:** [SchemaFormProps](/reference/studio-sdk/schema-forms#schemaformprops)

## SchemaFormErrors

```ts theme={null}
type SchemaFormErrors = Readonly<Record<string, string>>
```

A structured, per-path bag of validation problems. Keys are dotted/bracketed
paths from the form root (`""` = the root value, `"user.name"`, `"tags[0]"`);
each entry is a loud, human-readable message. Empty object = valid.

## SchemaFormProps

```ts theme={null}
interface SchemaFormProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `completionProvider?` | `CompletionProvider` | Optional. When supplied, every string field renders through the completion-backed input (argument autocomplete); when omitted, string fields render as a plain text input — the default, unchanged behaviour. |
| `errors?` | `Readonly<Record<string, string>>` | — |
| `expressionField?` | `ExpressionFieldComponent` | Optional. The expression-authoring door for `x-tai42-expression` fields — `JqField` from `@tai42/jq-studio`, which the host imports directly and passes here (see the module doc-comment). Omitted, the enclosing ExpressionFieldContext supplies it; absent both, an annotated field renders the plain string input. |
| `fieldWording?` | `Readonly<Record<string, FieldWords>>` | Optional. Per-field words, keyed by the root object's property name. A top-level `enum` field that draws as a select shows its entry's `choiceLabel` as the select placeholder (in place of the default `Select…`); a top-level list field draws its entry's `addItem`, `removeItem`, `itemLabel` (`{n}` the item's number) and `noItems` (in place of `Add item`, `Remove`, `Item {n}` and `No items`). Nested fields and other controls are unaffected, and a field with no entry draws the defaults. The entry's `invalid` and `required` sentences are not read here: pass the same record to `validateAgainstSchema` as `fieldWording`, and the errors it returns carry them. |
| `idPrefix?` | `string` | — |
| `maxUploadBytes?` | `number` | Optional. Default byte cap for media-upload fields (see the module doc-comment). A field's own `contentMaxBytes` annotation overrides it; absent both, DEFAULT\_MAX\_UPLOAD\_BYTES applies. |
| `onChange` | `(value: unknown) => void` | — |
| `schema` | `JsonSchema` | — |
| `value` | `unknown` | — |

**Related:** [CompletionProvider](/reference/studio-sdk/schema-forms#completionprovider), [ExpressionFieldComponent](/reference/studio-sdk/schema-forms#expressionfieldcomponent), [FieldWords](/reference/studio-sdk/schema-forms#fieldwords), [JsonSchema](/reference/studio-sdk/schema-forms#jsonschema)

## SecretRef

```ts theme={null}
type SecretRef = { key: string; source: "key" } | { secret: string; source: "paste" }
```

The value `SecretRefField` emits and reads back. The `source` discriminant
is what the host branches on:

* `key`   — reference an existing env key; the host resolves the reference.
* `paste` — a new plaintext secret; the host stores it under a generated key
  and records the reference. `secret` is write-only and never rendered.

## SecretRefField

```ts theme={null}
function SecretRefField(props: SecretRefFieldProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `availableKeys` | `readonly string[]` | Env key NAMES the host supplies (e.g. envConfig.secret\_keys). Never fetched here. |
| `idPrefix?` | `string` | — |
| `initialMode?` | `"key" \| "paste"` | Which editor a value-less field opens on when key picking is available. Defaults to `'paste'` (the write-first behaviour): a host adding a brand-new secret lands on the paste input. A host that only ever REFERENCES existing keys passes `'key'` so a fresh field opens straight on the key picker rather than a paste input it would block. Has no effect once a value is committed (the chip is shown) or when key picking is off (paste-only, fail closed). |
| `keyPickingAvailable?` | `boolean` | Whether env-key picking is available at all — the host passes it from whether the projection carries the env route. Omitted or false: paste-only (fail closed). |
| `label?` | `string` | Visible field label; the accessible name of the inner control. |
| `onChange` | `(value: SecretRef) => void` | Fired once when a value is provided (a key picked, or a paste committed). |
| `pasteDisabledReason?` | `string` | When set, PASTING a new secret is blocked and this reason is surfaced inline (referencing an existing key stays available). The host passes it when a paste right now would land in the wrong place — an unsaved structural edit has shifted the target pointer, or the entry has no key yet to hint the generated name. |
| `value` | `SecretRef \| undefined` | The current value, or `undefined` when nothing has been provided yet. |

**Related:** [SecretRefFieldProps](/reference/studio-sdk/schema-forms#secretreffieldprops)

## SecretRefFieldProps

```ts theme={null}
interface SecretRefFieldProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `availableKeys` | `readonly string[]` | Env key NAMES the host supplies (e.g. envConfig.secret\_keys). Never fetched here. |
| `idPrefix?` | `string` | — |
| `initialMode?` | `"key" \| "paste"` | Which editor a value-less field opens on when key picking is available. Defaults to `'paste'` (the write-first behaviour): a host adding a brand-new secret lands on the paste input. A host that only ever REFERENCES existing keys passes `'key'` so a fresh field opens straight on the key picker rather than a paste input it would block. Has no effect once a value is committed (the chip is shown) or when key picking is off (paste-only, fail closed). |
| `keyPickingAvailable?` | `boolean` | Whether env-key picking is available at all — the host passes it from whether the projection carries the env route. Omitted or false: paste-only (fail closed). |
| `label?` | `string` | Visible field label; the accessible name of the inner control. |
| `onChange` | `(value: SecretRef) => void` | Fired once when a value is provided (a key picked, or a paste committed). |
| `pasteDisabledReason?` | `string` | When set, PASTING a new secret is blocked and this reason is surfaced inline (referencing an existing key stays available). The host passes it when a paste right now would land in the wrong place — an unsaved structural edit has shifted the target pointer, or the entry has no key yet to hint the generated name. |
| `value` | `SecretRef \| undefined` | The current value, or `undefined` when nothing has been provided yet. |

**Related:** [SecretRef](/reference/studio-sdk/schema-forms#secretref)

## dateRangePairs

```ts theme={null}
function dateRangePairs(
  properties: readonly readonly [string, JsonSchema][],
): readonly DateRangePair[]
```

The date-range pairs among `properties` that are drawable as ONE control. A pair
qualifies when: the END names an existing sibling START in `rangeStart`; BOTH are
`format: date`; both carry the SAME `visibleWhen` (deep-equal, or both absent); AND
no OTHER field's `visibleWhen` names either end — otherwise merging the pair would
leave that field's predicate pointing at a control that no longer draws on its own,
so the pair stays two date fields (the documented degrade). `properties` is ONE
page's ordered list; a field is used in at most one pair. Each pair also names each
end's `timeOf` time among the same properties, which draws inside the group.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `properties` | `readonly readonly [string, JsonSchema][]` | — | — |

**Related:** [DateRangePair](/reference/studio-sdk/schema-forms#daterangepair), [JsonSchema](/reference/studio-sdk/schema-forms#jsonschema)

## defaultValueForSchema

```ts theme={null}
function defaultValueForSchema(schema: JsonSchema, root: JsonSchema): unknown
```

The initial value for a schema. `root` carries the `$defs` document for
`$ref` resolution and defaults to the schema itself (the common
whole-tool-schema call).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `schema` | `JsonSchema` | — | — |
| `root` | `JsonSchema` | `schema` | — |

**Related:** [JsonSchema](/reference/studio-sdk/schema-forms#jsonschema)

## fieldDrawingOrder

```ts theme={null}
function fieldDrawingOrder(
  names: readonly string[],
  properties: Readonly<Record<string, JsonSchema>>,
): string[]
```

`names` in drawing order: each `timeOf` time moved to sit right after the date it
names. `names` is one page's fields, or every property of a page-less form or a
readback, in their given order. A time moves only when the name it points at is in
`names` and does not itself point at another listed name; any other time (its date
not listed, a chain of times, a cycle) keeps its place. Every name appears exactly
once and every other name keeps its relative order. Pure and idempotent, so every
walker that orders the same list draws it the same way.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `names` | `readonly string[]` | — | — |
| `properties` | `Readonly<Record<string, JsonSchema>>` | — | — |

**Related:** [JsonSchema](/reference/studio-sdk/schema-forms#jsonschema)

## isFieldVisible

```ts theme={null}
function isFieldVisible(schema: JsonSchema, values: Record<string, unknown>): boolean
```

Whether a property carrying `schema.visibleWhen` is visible against the current
`values` of its enclosing object. Absent predicate ⇒ always visible. Exactly one of
`equals`/`in`/`notEmpty` must be present; otherwise the predicate is malformed and the
field stays visible.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `schema` | `JsonSchema` | — | — |
| `values` | `Record<string, unknown>` | — | — |

**Related:** [JsonSchema](/reference/studio-sdk/schema-forms#jsonschema)

## resolveRef

```ts theme={null}
function resolveRef(schema: JsonSchema, root: JsonSchema): JsonSchema
```

Resolve an internal `$ref` against the document root, following chained refs
(a `$ref` whose target is itself a `$ref`). Only same-document pointers are
supported (`#/$defs/Name`, `#/definitions/Name`, `#`); an external or
unresolvable ref throws LOUDLY rather than yielding a silent empty schema.
A schema with no `$ref` is returned unchanged. A pointer cycle throws.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `schema` | `JsonSchema` | — | — |
| `root` | `JsonSchema` | — | — |

**Related:** [JsonSchema](/reference/studio-sdk/schema-forms#jsonschema)

## validateAgainstSchema

```ts theme={null}
function validateAgainstSchema(
  schema: JsonSchema,
  value: unknown,
  options?: ValidateOptions,
): SchemaFormErrors
```

Validate `value` against `schema`, returning a per-path error bag (empty =
valid). The caller runs this before submit and feeds the result back to
`SchemaForm` for display. `options.maxUploadBytes` mirrors the renderer's
`maxUploadBytes` prop so a media field's byte cap is enforced identically here;
`options.fieldWording` puts a field's own `invalid` sentence in place of the
SDK's word for any shape error on that field, and its own `required` sentence in
place of the SDK's message for a missing required value at or inside that field.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `schema` | `JsonSchema` | — | — |
| `value` | `unknown` | — | — |
| `options` *(optional)* | `ValidateOptions` | — | — |

**Related:** [JsonSchema](/reference/studio-sdk/schema-forms#jsonschema), [SchemaFormErrors](/reference/studio-sdk/schema-forms#schemaformerrors)


# Utilities
Source: https://docs.tai42.ai/reference/studio-sdk/utilities

Shared helpers and re-exported types the SDK exposes.

Shared helpers and re-exported types the SDK exposes.

## AdapterCompileResult

```ts theme={null}
type AdapterCompileResult = { jq: string; ok: true } | { error: string; ok: false }
```

A compile outcome: the jq program, or a human error to surface loudly.

## AdapterMapping

```ts theme={null}
function AdapterMapping(props: AdapterMappingProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `declaredInput` | `readonly string[]` | The declared input keys of the update jq — one row each. Empty ⇒ raw jq only. |
| `onChange` | `(adapterJq: string \| null) => void` | Emits the adapter to store: a non-empty jq, or `null` for no adapter (never `''`). |
| `sources?` | `BindingSourceSchemas` | The output / input field paths a picker offers. |
| `suggestions?` | `readonly TemplateJqSuggestion[]` | Template jq offered as `tjq_<name>({…})` inserts in the jq escape hatch. |
| `value` | `string` | The current adapter jq (compiled or authored) stored on the update; `''` ⇒ none stored. |

**Related:** [AdapterMappingProps](/reference/studio-sdk/utilities#adaptermappingprops)

## AdapterMappingProps

```ts theme={null}
interface AdapterMappingProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `declaredInput` | `readonly string[]` | The declared input keys of the update jq — one row each. Empty ⇒ raw jq only. |
| `onChange` | `(adapterJq: string \| null) => void` | Emits the adapter to store: a non-empty jq, or `null` for no adapter (never `''`). |
| `sources?` | `BindingSourceSchemas` | The output / input field paths a picker offers. |
| `suggestions?` | `readonly TemplateJqSuggestion[]` | Template jq offered as `tjq_<name>({…})` inserts in the jq escape hatch. |
| `value` | `string` | The current adapter jq (compiled or authored) stored on the update; `''` ⇒ none stored. |

**Related:** [BindingSourceSchemas](/reference/studio-sdk/utilities#bindingsourceschemas), [TemplateJqSuggestion](/reference/studio-sdk/utilities#templatejqsuggestion)

## ApiClient

```ts theme={null}
type ApiClient = ReturnType<typeof createApiClient>
```

## BindingJqField

```ts theme={null}
function BindingJqField(props: BindingJqFieldProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `description?` | `ReactNode` | — |
| `error?` | `string` | — |
| `hideLabel?` | `boolean` | Render the field's own visible label visually hidden while keeping it as the control's accessible name — for a field mounted under a group header that already shows the label (a `TemplatedTextField` slot). Off by default, so a bare use (a mapping row's jq) keeps its visible label. |
| `label` | `string` | — |
| `onChange` | `(value: string) => void` | — |
| `placeholder?` | `string` | — |
| `suggestions?` | `readonly TemplateJqSuggestion[]` | Template jq offered as `tjq_<name>({…})` inserts under the field. |
| `value` | `string` | — |

**Related:** [BindingJqFieldProps](/reference/studio-sdk/utilities#bindingjqfieldprops)

## BindingJqFieldProps

```ts theme={null}
interface BindingJqFieldProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `description?` | `ReactNode` | — |
| `error?` | `string` | — |
| `hideLabel?` | `boolean` | Render the field's own visible label visually hidden while keeping it as the control's accessible name — for a field mounted under a group header that already shows the label (a `TemplatedTextField` slot). Off by default, so a bare use (a mapping row's jq) keeps its visible label. |
| `label` | `string` | — |
| `onChange` | `(value: string) => void` | — |
| `placeholder?` | `string` | — |
| `suggestions?` | `readonly TemplateJqSuggestion[]` | Template jq offered as `tjq_<name>({…})` inserts under the field. |
| `value` | `string` | — |

**Related:** [TemplateJqSuggestion](/reference/studio-sdk/utilities#templatejqsuggestion)

## BindingSourceSchemas

```ts theme={null}
interface BindingSourceSchemas
```

The schemas a field picker draws from when authoring an injection or an adapter:
the run's `output` and `input` fields (the state's fields ride each
`BindingStateOption`). Absent roots offer no picked field — the author uses
a literal or a jq expression instead.

**Properties**

| Property | Type | Description |
| - | - | - |
| `error?` | `string` | The tool-schema fetch failed — the field control shows a note but stays usable. |
| `input?` | `readonly SchemaFieldPath[]` | — |
| `loading?` | `boolean` | The tool-schema fetch that feeds the pickers is in flight. |
| `output?` | `readonly SchemaFieldPath[]` | — |

**Related:** [SchemaFieldPath](/reference/studio-sdk/utilities#schemafieldpath)

## BindingStateOption

```ts theme={null}
interface BindingStateOption
```

One state the editor may bind, with the templates already attached to it and its fields.

**Properties**

| Property | Type | Description |
| - | - | - |
| `attachedTemplates?` | `readonly string[]` | Templates already attached to the state (the rest attach on save). |
| `fields?` | `readonly SchemaFieldPath[]` | The state's own record fields, for the `state` source of a field picker. |
| `name` | `string` | — |

**Related:** [SchemaFieldPath](/reference/studio-sdk/utilities#schemafieldpath)

## BindingTemplateJqOption

```ts theme={null}
interface BindingTemplateJqOption
```

One template jq of an attached template, as the pickers present it.

**Properties**

| Property | Type | Description |
| - | - | - |
| `description?` | `string` | — |
| `name` | `string` | — |
| `params?` | `readonly string[]` | An `input` jq's declared params / an `update` jq's declared input keys. |
| `purpose` | `"input" \| "update"` | — |
| `writes?` | `readonly readonly string[][]` | An `update` jq's declared write paths, each a list of key segments. |

## BindingTemplateOption

```ts theme={null}
interface BindingTemplateOption
```

One template the editor may attach to a state (attach-on-use), with its template jq.

**Properties**

| Property | Type | Description |
| - | - | - |
| `attached?` | `boolean` | Whether this template is already attached to the chosen state (else: attach on save). |
| `description?` | `string` | — |
| `name` | `string` | — |
| `templateJq` | `readonly BindingTemplateJqOption[]` | — |

**Related:** [BindingTemplateJqOption](/reference/studio-sdk/utilities#bindingtemplatejqoption)

## BindingTemplatedJqField

```ts theme={null}
function BindingTemplatedJqField(props: BindingTemplatedJqFieldProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `description?` | `string` | — |
| `disabled?` | `boolean` | — |
| `error?` | `string` | — |
| `label` | `string` | — |
| `onChange` | `(value: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null) => void` | — |
| `placeholder?` | `string` | — |
| `required?` | `boolean` | The subject/adapter slots require a source; the rest are optional (`null` clears). |
| `suggestions?` | `readonly TemplateJqSuggestion[]` | — |
| `templates?` | `TemplatedTextCatalog` | — |
| `value` | `{ content?: string; id?: string; kwargs?: Record<string, unknown> } \| null` | — |

**Related:** [BindingTemplatedJqFieldProps](/reference/studio-sdk/utilities#bindingtemplatedjqfieldprops)

## BindingTemplatedJqFieldProps

```ts theme={null}
interface BindingTemplatedJqFieldProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `description?` | `string` | — |
| `disabled?` | `boolean` | — |
| `error?` | `string` | — |
| `label` | `string` | — |
| `onChange` | `(value: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null) => void` | — |
| `placeholder?` | `string` | — |
| `required?` | `boolean` | The subject/adapter slots require a source; the rest are optional (`null` clears). |
| `suggestions?` | `readonly TemplateJqSuggestion[]` | — |
| `templates?` | `TemplatedTextCatalog` | — |
| `value` | `{ content?: string; id?: string; kwargs?: Record<string, unknown> } \| null` | — |

**Related:** [TemplateJqSuggestion](/reference/studio-sdk/utilities#templatejqsuggestion), [TemplatedTextCatalog](/reference/studio-sdk/utilities#templatedtextcatalog)

## ENV\_MARKER\_PREFIX

```ts theme={null}
const ENV_MARKER_PREFIX: "!ENV "
```

The prefix that makes a string leaf an `!ENV` marker.

## EnvRef

```ts theme={null}
interface EnvRef
```

The reference of a single-reference marker leaf.

**Properties**

| Property | Type | Description |
| - | - | - |
| `default?` | `string` | The `:default` text (without the leading colon); absent for a bare reference. |
| `key` | `string` | — |

## FeatureDisabled

```ts theme={null}
function FeatureDisabled(props: FeatureDisabledProps): ReactNode
```

The muted, honest OFF state for a feature whose store this deployment has not
configured. A `role="status"` EmptyState (never the loud alert ErrorState): the
feature is not broken, it is simply off, and the copy shows the server's own
remediation message.

**Props**

| Prop | Type | Description |
| - | - | - |
| `feature` | `string` | The human name of the OFF feature, e.g. `Interactions`. |
| `message` | `string` | The server's own remediation line, shown verbatim (never a client-composed string). |

**Related:** [FeatureDisabledProps](/reference/studio-sdk/utilities#featuredisabledprops)

## FeatureDisabledProps

```ts theme={null}
interface FeatureDisabledProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `feature` | `string` | The human name of the OFF feature, e.g. `Interactions`. |
| `message` | `string` | The server's own remediation line, shown verbatim (never a client-composed string). |

## FieldRoot

```ts theme={null}
type FieldRoot = "output" | "input"
```

Which value a picked field reads: the tool output (the program's `.`) or the run input (`$input`).

## FieldSource

```ts theme={null}
interface FieldSource
```

A picked field: a path into the tool output or the run input.

**Properties**

| Property | Type | Description |
| - | - | - |
| `kind` | `"field"` | — |
| `path` | `readonly string[]` | — |
| `root` | `FieldRoot` | — |

**Related:** [FieldRoot](/reference/studio-sdk/utilities#fieldroot)

## InheritedSubject

```ts theme={null}
interface InheritedSubject
```

The subject/scope of the target's own (inherited) binding for a state this one also names.

**Properties**

| Property | Type | Description |
| - | - | - |
| `scope_expr` | `{ content?: string; id?: string; kwargs?: Record<string, unknown> } \| null` | — |
| `subject_expr` | `{ content?: string; id?: string; kwargs?: Record<string, unknown> }` | — |

## InjectionList

```ts theme={null}
function InjectionList(props: InjectionListProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `injections` | `readonly ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]` | — |
| `inputJq` | `readonly ResolvedTemplateJq[]` | — |
| `onChange` | `(injections: readonly ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]) => void` | — |
| `suggestions?` | `readonly TemplateJqSuggestion[]` | — |
| `templates?` | `TemplatedTextCatalog` | — |

**Related:** [InjectionListProps](/reference/studio-sdk/utilities#injectionlistprops)

## InjectionListProps

```ts theme={null}
interface InjectionListProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `injections` | `readonly ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]` | — |
| `inputJq` | `readonly ResolvedTemplateJq[]` | — |
| `onChange` | `(injections: readonly ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]) => void` | — |
| `suggestions?` | `readonly TemplateJqSuggestion[]` | — |
| `templates?` | `TemplatedTextCatalog` | — |

**Related:** [ResolvedTemplateJq](/reference/studio-sdk/utilities#resolvedtemplatejq), [TemplateJqSuggestion](/reference/studio-sdk/utilities#templatejqsuggestion), [TemplatedTextCatalog](/reference/studio-sdk/utilities#templatedtextcatalog)

## JqSource

```ts theme={null}
interface JqSource
```

A raw jq expression over the tool output (its `.`), with the run input bound as `$input`.

**Properties**

| Property | Type | Description |
| - | - | - |
| `expr` | `string` | — |
| `kind` | `"jq"` | — |

## LiteralSource

```ts theme={null}
interface LiteralSource
```

A hardcoded literal, authored as JSON text (`"a"`, `42`, `true`, `{…}`).

**Properties**

| Property | Type | Description |
| - | - | - |
| `json` | `string` | — |
| `kind` | `"literal"` | — |

## MappingRow

```ts theme={null}
interface MappingRow
```

One mapping row: a target key of the update jq's declared input + its value source.

**Properties**

| Property | Type | Description |
| - | - | - |
| `source` | `MappingSource` | — |
| `target` | `string` | — |

**Related:** [MappingSource](/reference/studio-sdk/utilities#mappingsource)

## MappingSource

```ts theme={null}
type MappingSource = FieldSource | LiteralSource | JqSource
```

The three value sources one mapping row may carry — exactly one at a time.

**Related:** [FieldSource](/reference/studio-sdk/utilities#fieldsource), [JqSource](/reference/studio-sdk/utilities#jqsource), [LiteralSource](/reference/studio-sdk/utilities#literalsource)

## ResolvedTemplateJq

```ts theme={null}
interface ResolvedTemplateJq extends BindingTemplateJqOption
```

One template jq of an attached template, resolved to the reference a binding stores.

**Properties**

| Property | Type | Description |
| - | - | - |
| `description?` | `string` | — |
| `name` | `string` | — |
| `params?` | `readonly string[]` | An `input` jq's declared params / an `update` jq's declared input keys. |
| `purpose` | `"input" \| "update"` | — |
| `ref` | `string` | The reference a binding writes: `name`, or `template.name` when ambiguous. |
| `template` | `string` | The owning template. |
| `writes?` | `readonly readonly string[][]` | An `update` jq's declared write paths, each a list of key segments. |

**Related:** [BindingTemplateJqOption](/reference/studio-sdk/utilities#bindingtemplatejqoption)

## RunAnswer

```ts theme={null}
type RunAnswer = z.infer<typeof runAnswer>
```

What `useApi().runTool` resolves with: the run-tool door's answer, read by its `kind`.

## SchemaEditor

```ts theme={null}
function SchemaEditor(props: SchemaEditorProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `description?` | `string` | — |
| `disabled?` | `boolean` | — |
| `hideLabel?` | `boolean` | Render the field label for ASSISTIVE TECH ONLY — visually hidden but still the editor's accessible name. Used when a host control already draws the visible label above this editor (e.g. an authored-body control whose inline editor this is), so the heading is not drawn twice. Forwarded to the underlying Field. |
| `idPrefix?` | `string` | — |
| `label?` | `string` | — |
| `onChange` | `(change: SchemaEditorChange) => void` | Fired on every edit with the parsed schema (or `null`) and its validity. |
| `requireTitle` | `boolean` | When true, a top-level `"title"` is required (the `response_format` contract). |
| `value` | `Record<string, unknown> \| null` | The schema dict to seed the editor with, or `null` for an empty editor. |

**Related:** [SchemaEditorProps](/reference/studio-sdk/utilities#schemaeditorprops)

## SchemaEditorChange

```ts theme={null}
interface SchemaEditorChange
```

What `SchemaEditor` reports up on every edit.

**Properties**

| Property | Type | Description |
| - | - | - |
| `schema` | `Record<string, unknown> \| null` | The authored schema dict when valid and non-empty; `null` when the editor is empty. |
| `valid` | `boolean` | False when the text is non-empty but unparseable or failing lint — gate submit on this. |

## SchemaEditorProps

```ts theme={null}
interface SchemaEditorProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `description?` | `string` | — |
| `disabled?` | `boolean` | — |
| `hideLabel?` | `boolean` | Render the field label for ASSISTIVE TECH ONLY — visually hidden but still the editor's accessible name. Used when a host control already draws the visible label above this editor (e.g. an authored-body control whose inline editor this is), so the heading is not drawn twice. Forwarded to the underlying Field. |
| `idPrefix?` | `string` | — |
| `label?` | `string` | — |
| `onChange` | `(change: SchemaEditorChange) => void` | Fired on every edit with the parsed schema (or `null`) and its validity. |
| `requireTitle` | `boolean` | When true, a top-level `"title"` is required (the `response_format` contract). |
| `value` | `Record<string, unknown> \| null` | The schema dict to seed the editor with, or `null` for an empty editor. |

**Related:** [SchemaEditorChange](/reference/studio-sdk/utilities#schemaeditorchange)

## SchemaFieldPath

```ts theme={null}
interface SchemaFieldPath
```

One selectable field of a schema: the record path + a human label.

**Properties**

| Property | Type | Description |
| - | - | - |
| `label` | `string` | — |
| `path` | `readonly string[]` | — |

## SchemaLintResult

```ts theme={null}
interface SchemaLintResult
```

The parse/lint outcome for one editor text buffer.

**Properties**

| Property | Type | Description |
| - | - | - |
| `error` | `string \| undefined` | A loud, human-readable message when valid is false; else `undefined`. |
| `schema` | `Record<string, unknown> \| null` | The parsed schema dict when the text is a syntactically valid JSON object, or `null` when the text is empty or does not parse. Carries the parsed object even when a lint (e.g. a missing `title`) fails, so the preview can still show the authored shape — the consumer gates on valid, never on this alone. |
| `valid` | `boolean` | True when the text is empty or a valid schema. False when the text is non-empty but fails to parse or fails a structural lint — the consumer blocks submit. |

## StateAttachRow

```ts theme={null}
function StateAttachRow(props: StateAttachRowProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `attach` | `{ input_injections: ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]; scope_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; state: string; subject_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> }; templates: string[]; updates: ({ adapter: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[] }` | — |
| `inherited?` | `InheritedSubject` | The target's own binding subject for this state, when it also binds it (precedence). |
| `onChange` | `(attach: { input_injections: ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]; scope_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; state: string; subject_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> }; templates: string[]; updates: ({ adapter: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[] }) => void` | — |
| `onRemove` | `() => void` | — |
| `sources?` | `BindingSourceSchemas` | — |
| `statesCatalog` | `readonly BindingStateOption[]` | — |
| `subjectError?` | `string` | — |
| `templates?` | `TemplatedTextCatalog` | The stored templates a templated-text field's id picker offers. |
| `templatesCatalog` | `readonly BindingTemplateOption[]` | — |

**Related:** [StateAttachRowProps](/reference/studio-sdk/utilities#stateattachrowprops)

## StateAttachRowProps

```ts theme={null}
interface StateAttachRowProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `attach` | `{ input_injections: ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]; scope_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; state: string; subject_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> }; templates: string[]; updates: ({ adapter: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[] }` | — |
| `inherited?` | `InheritedSubject` | The target's own binding subject for this state, when it also binds it (precedence). |
| `onChange` | `(attach: { input_injections: ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]; scope_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; state: string; subject_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> }; templates: string[]; updates: ({ adapter: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[] }) => void` | — |
| `onRemove` | `() => void` | — |
| `sources?` | `BindingSourceSchemas` | — |
| `statesCatalog` | `readonly BindingStateOption[]` | — |
| `subjectError?` | `string` | — |
| `templates?` | `TemplatedTextCatalog` | The stored templates a templated-text field's id picker offers. |
| `templatesCatalog` | `readonly BindingTemplateOption[]` | — |

**Related:** [BindingSourceSchemas](/reference/studio-sdk/utilities#bindingsourceschemas), [BindingStateOption](/reference/studio-sdk/utilities#bindingstateoption), [BindingTemplateOption](/reference/studio-sdk/utilities#bindingtemplateoption), [InheritedSubject](/reference/studio-sdk/utilities#inheritedsubject), [TemplatedTextCatalog](/reference/studio-sdk/utilities#templatedtextcatalog)

## StateBindingEditor

```ts theme={null}
function StateBindingEditor(props: StateBindingEditorProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `error?` | `string` | The catalog fetch failed. |
| `inherited?` | `{ states: ({ input_injections: ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]; scope_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; state: string; subject_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> }; templates: string[]; updates: ({ adapter: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[] })[] } \| null` | The TARGET's own binding (e.g. the preset a route dispatches), passed by the door screen — never fetched here. A state this binding names that the inherited one also names shows a precedence warning on its card. |
| `loading?` | `boolean` | The catalog fetch is in flight. |
| `onChange` | `(value: { states: ({ input_injections: ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<..., ...> } \| null; template_jq: string \| null })[]; scope_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; state: string; subject_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> }; templates: string[]; updates: ({ adapter: { content?: string; id?: string; kwargs?: Record<..., ...> } \| null; jq: { content?: string; id?: string; kwargs?: Record<..., ...> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<..., ...> } \| null; template_jq: string \| null })[] })[] } \| null) => void` | — |
| `sources?` | `BindingSourceSchemas` | The run's output/input field paths a picker offers when a schema is known. |
| `statesCatalog` | `readonly BindingStateOption[]` | The states this door may bind, each with its attached templates and fields. |
| `templatedTextTemplates?` | `TemplatedTextCatalog` | The stored templates a templated-text field's id picker offers, resolved by the door. |
| `templatesCatalog` | `readonly BindingTemplateOption[]` | The templates the editor may attach (attach-on-use), each with its template jq. |
| `value` | `{ states: ({ input_injections: ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]; scope_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; state: string; subject_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> }; templates: string[]; updates: ({ adapter: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[] })[] } \| null` | The binding, or `null` when the door binds no state. |

**Related:** [StateBindingEditorProps](/reference/studio-sdk/utilities#statebindingeditorprops)

## StateBindingEditorProps

```ts theme={null}
interface StateBindingEditorProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `error?` | `string` | The catalog fetch failed. |
| `inherited?` | `{ states: ({ input_injections: ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]; scope_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; state: string; subject_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> }; templates: string[]; updates: ({ adapter: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[] })[] } \| null` | The TARGET's own binding (e.g. the preset a route dispatches), passed by the door screen — never fetched here. A state this binding names that the inherited one also names shows a precedence warning on its card. |
| `loading?` | `boolean` | The catalog fetch is in flight. |
| `onChange` | `(value: { states: ({ input_injections: ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<..., ...> } \| null; template_jq: string \| null })[]; scope_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; state: string; subject_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> }; templates: string[]; updates: ({ adapter: { content?: string; id?: string; kwargs?: Record<..., ...> } \| null; jq: { content?: string; id?: string; kwargs?: Record<..., ...> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<..., ...> } \| null; template_jq: string \| null })[] })[] } \| null) => void` | — |
| `sources?` | `BindingSourceSchemas` | The run's output/input field paths a picker offers when a schema is known. |
| `statesCatalog` | `readonly BindingStateOption[]` | The states this door may bind, each with its attached templates and fields. |
| `templatedTextTemplates?` | `TemplatedTextCatalog` | The stored templates a templated-text field's id picker offers, resolved by the door. |
| `templatesCatalog` | `readonly BindingTemplateOption[]` | The templates the editor may attach (attach-on-use), each with its template jq. |
| `value` | `{ states: ({ input_injections: ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]; scope_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; state: string; subject_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> }; templates: string[]; updates: ({ adapter: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[] })[] } \| null` | The binding, or `null` when the door binds no state. |

**Related:** [BindingSourceSchemas](/reference/studio-sdk/utilities#bindingsourceschemas), [BindingStateOption](/reference/studio-sdk/utilities#bindingstateoption), [BindingTemplateOption](/reference/studio-sdk/utilities#bindingtemplateoption), [TemplatedTextCatalog](/reference/studio-sdk/utilities#templatedtextcatalog)

## StateBindingSection

```ts theme={null}
function StateBindingSection(props: StateBindingSectionProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `error?` | `string` | The catalog fetch failed. |
| `inherited?` | `{ states: ({ input_injections: ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]; scope_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; state: string; subject_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> }; templates: string[]; updates: ({ adapter: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[] })[] } \| null` | The TARGET's own binding (e.g. the preset a route dispatches), passed by the door screen — never fetched here. A state this binding names that the inherited one also names shows a precedence warning on its card. |
| `label?` | `string` | Copy on the disclosure toggle. |
| `loading?` | `boolean` | The catalog fetch is in flight. |
| `onChange` | `(value: { states: ({ input_injections: ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<..., ...> } \| null; template_jq: string \| null })[]; scope_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; state: string; subject_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> }; templates: string[]; updates: ({ adapter: { content?: string; id?: string; kwargs?: Record<..., ...> } \| null; jq: { content?: string; id?: string; kwargs?: Record<..., ...> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<..., ...> } \| null; template_jq: string \| null })[] })[] } \| null) => void` | — |
| `sources?` | `BindingSourceSchemas` | The run's output/input field paths a picker offers when a schema is known. |
| `statesCatalog` | `readonly BindingStateOption[]` | The states this door may bind, each with its attached templates and fields. |
| `templatedTextTemplates?` | `TemplatedTextCatalog` | The stored templates a templated-text field's id picker offers, resolved by the door. |
| `templatesCatalog` | `readonly BindingTemplateOption[]` | The templates the editor may attach (attach-on-use), each with its template jq. |
| `value` | `{ states: ({ input_injections: ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]; scope_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; state: string; subject_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> }; templates: string[]; updates: ({ adapter: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[] })[] } \| null` | The binding, or `null` when the door binds no state. |

**Related:** [StateBindingSectionProps](/reference/studio-sdk/utilities#statebindingsectionprops)

## StateBindingSectionProps

```ts theme={null}
interface StateBindingSectionProps extends StateBindingEditorProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `error?` | `string` | The catalog fetch failed. |
| `inherited?` | `{ states: ({ input_injections: ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]; scope_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; state: string; subject_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> }; templates: string[]; updates: ({ adapter: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[] })[] } \| null` | The TARGET's own binding (e.g. the preset a route dispatches), passed by the door screen — never fetched here. A state this binding names that the inherited one also names shows a precedence warning on its card. |
| `label?` | `string` | Copy on the disclosure toggle. |
| `loading?` | `boolean` | The catalog fetch is in flight. |
| `onChange` | `(value: { states: ({ input_injections: ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<..., ...> } \| null; template_jq: string \| null })[]; scope_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; state: string; subject_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> }; templates: string[]; updates: ({ adapter: { content?: string; id?: string; kwargs?: Record<..., ...> } \| null; jq: { content?: string; id?: string; kwargs?: Record<..., ...> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<..., ...> } \| null; template_jq: string \| null })[] })[] } \| null) => void` | — |
| `sources?` | `BindingSourceSchemas` | The run's output/input field paths a picker offers when a schema is known. |
| `statesCatalog` | `readonly BindingStateOption[]` | The states this door may bind, each with its attached templates and fields. |
| `templatedTextTemplates?` | `TemplatedTextCatalog` | The stored templates a templated-text field's id picker offers, resolved by the door. |
| `templatesCatalog` | `readonly BindingTemplateOption[]` | The templates the editor may attach (attach-on-use), each with its template jq. |
| `value` | `{ states: ({ input_injections: ({ into: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]; scope_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; state: string; subject_expr: { content?: string; id?: string; kwargs?: Record<string, unknown> }; templates: string[]; updates: ({ adapter: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[] })[] } \| null` | The binding, or `null` when the door binds no state. |

**Related:** [BindingSourceSchemas](/reference/studio-sdk/utilities#bindingsourceschemas), [BindingStateOption](/reference/studio-sdk/utilities#bindingstateoption), [BindingTemplateOption](/reference/studio-sdk/utilities#bindingtemplateoption), [StateBindingEditorProps](/reference/studio-sdk/utilities#statebindingeditorprops), [TemplatedTextCatalog](/reference/studio-sdk/utilities#templatedtextcatalog)

## StoragePresenceQueryLike

```ts theme={null}
interface StoragePresenceQueryLike
```

The storage-presence query result (`GET /api/storage`) fields this helper reads.

**Properties**

| Property | Type | Description |
| - | - | - |
| `data?` | `{ present: boolean }` | — |
| `error` | `unknown` | — |
| `isError` | `boolean` | — |
| `isPending` | `boolean` | — |
| `refetch` | `() => unknown` | — |

## SubjectScopeFields

```ts theme={null}
function SubjectScopeFields(props: SubjectScopeFieldsProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `onScopeChange` | `(value: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null) => void` | — |
| `onSubjectChange` | `(value: { content?: string; id?: string; kwargs?: Record<string, unknown> }) => void` | — |
| `scopeExpr` | `{ content?: string; id?: string; kwargs?: Record<string, unknown> } \| null` | — |
| `subjectError?` | `string` | — |
| `subjectExpr` | `{ content?: string; id?: string; kwargs?: Record<string, unknown> }` | — |
| `suggestions?` | `readonly TemplateJqSuggestion[]` | — |
| `templates?` | `TemplatedTextCatalog` | — |

**Related:** [SubjectScopeFieldsProps](/reference/studio-sdk/utilities#subjectscopefieldsprops)

## SubjectScopeFieldsProps

```ts theme={null}
interface SubjectScopeFieldsProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `onScopeChange` | `(value: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null) => void` | — |
| `onSubjectChange` | `(value: { content?: string; id?: string; kwargs?: Record<string, unknown> }) => void` | — |
| `scopeExpr` | `{ content?: string; id?: string; kwargs?: Record<string, unknown> } \| null` | — |
| `subjectError?` | `string` | — |
| `subjectExpr` | `{ content?: string; id?: string; kwargs?: Record<string, unknown> }` | — |
| `suggestions?` | `readonly TemplateJqSuggestion[]` | — |
| `templates?` | `TemplatedTextCatalog` | — |

**Related:** [TemplateJqSuggestion](/reference/studio-sdk/utilities#templatejqsuggestion), [TemplatedTextCatalog](/reference/studio-sdk/utilities#templatedtextcatalog)

## TemplateJqSuggestion

```ts theme={null}
interface TemplateJqSuggestion
```

One template jq offered as an insertable autocomplete entry.

**Properties**

| Property | Type | Description |
| - | - | - |
| `description?` | `string` | — |
| `purpose` | `"input" \| "update"` | — |
| `ref` | `string` | The jq reference, e.g. `active` or the attachment-qualified `tally.bump`. |

## TemplateNamesQueryLike

```ts theme={null}
interface TemplateNamesQueryLike
```

The stored-template-names query result (`GET /api/templates`) fields this helper reads.

**Properties**

| Property | Type | Description |
| - | - | - |
| `data?` | `readonly string[]` | — |
| `error` | `unknown` | — |
| `isError` | `boolean` | — |
| `isPending` | `boolean` | — |
| `refetch` | `() => unknown` | — |

## TemplatedText

```ts theme={null}
type TemplatedText = z.infer<typeof templatedText>
```

## TemplatedTextCatalog

```ts theme={null}
interface TemplatedTextCatalog
```

The stored templates a `TemplatedText` field's id picker offers, with the
fetch's loading/error state — resolved by the door screen and passed to the
editor, which holds no data edge of its own. Absent leaves every templated-text
field with the inline source only.

**Properties**

| Property | Type | Description |
| - | - | - |
| `error?` | `string` | — |
| `loading?` | `boolean` | — |
| `onRetry?` | `() => void` | — |
| `storageAbsent?` | `boolean` | Storage is registered absent (`GET /api/storage` → `present: false`), so the catalog was not fetched and the stored source is not offered on the fields this catalog feeds; an already-stored id is shown read-only. |
| `storagePresenceLoading?` | `boolean` | Storage presence is not yet known — the fields render a placeholder, not a toggle. |
| `templates?` | `readonly TemplatedTextTemplateOption[]` | — |

**Related:** [TemplatedTextTemplateOption](/reference/studio-sdk/components#templatedtexttemplateoption)

## UpdateList

```ts theme={null}
function UpdateList(props: UpdateListProps): ReactNode
```

**Props**

| Prop | Type | Description |
| - | - | - |
| `onChange` | `(updates: readonly ({ adapter: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]) => void` | — |
| `sources?` | `BindingSourceSchemas` | — |
| `suggestions?` | `readonly TemplateJqSuggestion[]` | — |
| `templates?` | `TemplatedTextCatalog` | — |
| `updateJq` | `readonly ResolvedTemplateJq[]` | — |
| `updates` | `readonly ({ adapter: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]` | — |

**Related:** [UpdateListProps](/reference/studio-sdk/utilities#updatelistprops)

## UpdateListProps

```ts theme={null}
interface UpdateListProps
```

**Properties**

| Property | Type | Description |
| - | - | - |
| `onChange` | `(updates: readonly ({ adapter: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]) => void` | — |
| `sources?` | `BindingSourceSchemas` | — |
| `suggestions?` | `readonly TemplateJqSuggestion[]` | — |
| `templates?` | `TemplatedTextCatalog` | — |
| `updateJq` | `readonly ResolvedTemplateJq[]` | — |
| `updates` | `readonly ({ adapter: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; op_id: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; template_jq: string \| null })[]` | — |

**Related:** [BindingSourceSchemas](/reference/studio-sdk/utilities#bindingsourceschemas), [ResolvedTemplateJq](/reference/studio-sdk/utilities#resolvedtemplatejq), [TemplateJqSuggestion](/reference/studio-sdk/utilities#templatejqsuggestion), [TemplatedTextCatalog](/reference/studio-sdk/utilities#templatedtextcatalog)

## appendTjq

```ts theme={null}
function appendTjq(current: string, ref: string): string
```

Append a `tjq_<name>({…})` template call to the current expression (space-separated when non-empty).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `current` | `string` | — | — |
| `ref` | `string` | — | — |

## collectEnvRefs

```ts theme={null}
function collectEnvRefs(value: unknown): Set<string>
```

Every variable name any marker leaf anywhere under `value` references.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `unknown` | — | — |

## comboElementNames

```ts theme={null}
function comboElementNames(
  combo: readonly (string | { config: z.ZodRecord<z.ZodString, z.ZodUnknown>; name: string })[],
): string[]
```

Project a combo's elements to their bare extension names (drops any `config`).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `combo` | `readonly (string \| { config: z.ZodRecord<z.ZodString, z.ZodUnknown>; name: string })[]` | — | — |

## compileAdapter

```ts theme={null}
function compileAdapter(rows: readonly MappingRow[]): AdapterCompileResult
```

Compile a mapping form into ONE adapter jq that constructs the update jq's
declared input over the tool output and `$input`. An empty form compiles to the
empty object `{}`; a blank target, a duplicate target, or an invalid source is a
loud error.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `rows` | `readonly MappingRow[]` | — | — |

**Related:** [AdapterCompileResult](/reference/studio-sdk/utilities#adaptercompileresult), [MappingRow](/reference/studio-sdk/utilities#mappingrow)

## defaultRowsForInput

```ts theme={null}
function defaultRowsForInput(params: readonly string[]): MappingRow[]
```

One row per declared input key, each defaulting to a picked `output` field.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `params` | `readonly string[]` | — | — |

**Related:** [MappingRow](/reference/studio-sdk/utilities#mappingrow)

## downloadBlob

```ts theme={null}
function downloadBlob(blob: Blob, filename: string): void
```

Stream a `Blob` (an export- or content-route response) to the user as a file
download via a transient object URL. The object URL is revoked on the next tick —
revoking it synchronously can cancel the download before the browser commits it.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `blob` | `Blob` | — | — |
| `filename` | `string` | — | — |

## effectiveHidden

```ts theme={null}
function effectiveHidden(
  overlayHidden: boolean | null | undefined,
  declaredHidden: boolean,
): boolean
```

Effective hidden after the tri-state override. `overlayHidden` is the overlay's
`hidden` (`true`/`false`), or `null`/`undefined` when the overlay defers or has
no row; `declaredHidden` is the plugin's own `hidden`. Overlay opinion wins;
absence defers to the declaration.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `overlayHidden` | `boolean \| null \| undefined` | — | — |
| `declaredHidden` | `boolean` | — | — |

## encodeTemplateSegment

```ts theme={null}
function encodeTemplateSegment(template: string): string
```

Encode a template-name slug for a jq identifier: each `-` becomes `_`. Under the slug
invariant (no consecutive or trailing hyphens) the result carries no `__` and no
trailing `_`, which is what makes the first `__` in a call name the template boundary.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `template` | `string` | — | — |

## errorMessage

```ts theme={null}
function errorMessage(error: unknown): string
```

Normalize an unknown thrown/rejected value (a TanStack Query `error`, a
rejected mutation, a zod/`ApiError`) into a human-readable string for the loud
`ErrorState` / `Field` surfaces. This only turns a caught value into
displayable text — it never swallows the failure; the caller decides where to
show it, and the message is always shown, never blank.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `error` | `unknown` | — | — |

## extensionElementName

```ts theme={null}
function extensionElementName(
  element: string | { config: z.ZodRecord<z.ZodString, z.ZodUnknown>; name: string },
): string
```

The bare extension name of one combo element (drops any `config`).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `element` | `string \| { config: z.ZodRecord<z.ZodString, z.ZodUnknown>; name: string }` | — | — |

## extensionsQueryKey

```ts theme={null}
const extensionsQueryKey: readonly ["extensions"]
```

The extension catalog (`GET /api/extensions`). The extensions feature keys its
read-only catalog on it; a tool's extension-combo save (in the tools feature)
creates or tears down branch tools, so it invalidates this key too — a
cross-feature reference that must resolve to one authoritative constant.

## featureDisabledMessage

```ts theme={null}
function featureDisabledMessage(error: unknown): string
```

The remediation line for a refusal: the skeleton's own `message` (which names the
missing configuration), else its machine `code`. The client NEVER composes this —
a refusal carrying neither is a contract breach and raises.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `error` | `unknown` | — | — |

## fieldPathToJq

```ts theme={null}
function fieldPathToJq(root: FieldRoot, path: readonly string[]): string
```

A picked field rendered as a jq path: an output field reads off the program root
(`.user.name`, `.["odd key"]`, the whole output `.`), an input field off the bound run
input (`$input.user.name`, the whole input `$input`).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `root` | `FieldRoot` | — | — |
| `path` | `readonly string[]` | — | — |

**Related:** [FieldRoot](/reference/studio-sdk/utilities#fieldroot)

## fieldPathsFromSchema

```ts theme={null}
function fieldPathsFromSchema(schema: unknown): SchemaFieldPath[]
```

Flatten a JSON schema's `properties` into selectable field paths (top-level and
every nested object level), each labelled with its dotted path — the picker source
for the adapter's `output`/`input` roots. A non-object or property-less schema
yields no fields (the field control then falls back to a free path input).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `schema` | `unknown` | — | — |

**Related:** [SchemaFieldPath](/reference/studio-sdk/utilities#schemafieldpath)

## findByRef

```ts theme={null}
function findByRef(
  ref: string,
  resolved: readonly ResolvedTemplateJq[],
): ResolvedTemplateJq | undefined
```

Find one resolved template jq by the reference a binding stores.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `ref` | `string` | — | — |
| `resolved` | `readonly ResolvedTemplateJq[]` | — | — |

**Related:** [ResolvedTemplateJq](/reference/studio-sdk/utilities#resolvedtemplatejq)

## formatEnvMarker

```ts theme={null}
function formatEnvMarker(key: string, defaultValue?: string): string
```

The marker referencing `key`, carrying `defaultValue` when given. Throws when
`parseEnvMarker` would not read the marker back as `(key, defaultValue)`: a name is
non-empty and carries no `{`, `}` or `:`; a default is non-empty and carries no `}`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `key` | `string` | — | — |
| `defaultValue` *(optional)* | `string` | — | — |

## generateTemplateCall

```ts theme={null}
function generateTemplateCall(ref: string, rows: readonly MappingRow[]): string
```

The single-expression form of a named template update built from a mapping form:
`tjq_<enc(template)>__<name>({…})` for a qualified ref, `tjq_<name>({…})` for a bare
one (see the module note on the `__` boundary invariant).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `ref` | `string` | — | — |
| `rows` | `readonly MappingRow[]` | — | — |

**Related:** [MappingRow](/reference/studio-sdk/utilities#mappingrow)

## hiddenToolNames

```ts theme={null}
function hiddenToolNames(
  tagEntries: readonly ({ badges: string[]; hidden: boolean; name: string; schedulable: boolean; tags: string[] })[],
  overlayRows: readonly ({ badges: string[]; display_name: string | null; folder_id: string | null; hidden: boolean | null; tags: string[]; tool_name: string })[],
): Set<string>
```

The set of tool names whose EFFECTIVE visibility is hidden, from the native
declarations (`listToolTags`) merged with the tool\_meta overlay (`listToolMeta`).
A picker excludes exactly these names from its options; the server stays the
authority (a slipped-through name is rejected loudly there), so a name in the set
that is not among a picker's options is simply inert.

The union of both sources is walked so an overlay row that force-hides a tool
carrying no native tag entry is still caught, and an overlay `false` on a
plugin-hidden tool correctly keeps it OUT of the set (unhidden).

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `tagEntries` | `readonly ({ badges: string[]; hidden: boolean; name: string; schedulable: boolean; tags: string[] })[]` | — | — |
| `overlayRows` | `readonly ({ badges: string[]; display_name: string \| null; folder_id: string \| null; hidden: boolean \| null; tags: string[]; tool_name: string })[]` | — | — |

## isFeatureDisabled

```ts theme={null}
function isFeatureDisabled(error: unknown): boolean
```

True when `error` is a disabled-feature refusal from the skeleton: an HTTP 501, or
a `code` ending `-not-configured`. The `code` is authoritative; the 501 status is
the fallback signal — either alone is enough.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `error` | `unknown` | — | — |

## jqKey

```ts theme={null}
function jqKey(key: string): string
```

An object key rendered for jq: a bare identifier, or a quoted string otherwise.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `key` | `string` | — | — |

## lintSchemaText

```ts theme={null}
function lintSchemaText(text: string, requireTitle: boolean): SchemaLintResult
```

Parse and structurally lint a JSON-Schema editor buffer.

* Empty text is VALID (an unset, optional schema) with a `null` schema.
* Malformed JSON is INVALID; the parser message is surfaced verbatim.
* A top-level value that is not a JSON object (an array or a scalar) is INVALID.
* When `requireTitle`, a top-level string `"title"` is REQUIRED (the
  `response_format` contract the backend enforces); its absence is INVALID.

The parsed object is returned untouched — no key is normalized, reordered, or
dropped — so a schema carrying `$defs`/`anyOf` round-trips exactly.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `text` | `string` | — | — |
| `requireTitle` | `boolean` | — | — |

**Related:** [SchemaLintResult](/reference/studio-sdk/utilities#schemalintresult)

## mergeToolBadges

```ts theme={null}
function mergeToolBadges(
  nativeBadges: readonly string[],
  overlayBadges: readonly string[],
): readonly string[]
```

A tool's effective badges: native ∪ overlay, deduped and case-insensitively sorted.
The atomic rule every badge surface merges by, so the tools list and the pickers
show one and the same set.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `nativeBadges` | `readonly string[]` | — | — |
| `overlayBadges` | `readonly string[]` | — | — |

## parseAdapter

```ts theme={null}
function parseAdapter(jq: string): MappingRow[] | null
```

Recover the mapping rows from a stored adapter jq, or `null` if it is not the generated shape.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `jq` | `string` | — | — |

**Related:** [MappingRow](/reference/studio-sdk/utilities#mappingrow)

## parseEnvMarker

```ts theme={null}
function parseEnvMarker(value: unknown): EnvRef | null
```

The reference of `value` when it is exactly `!ENV ${KEY}` or `!ENV ${KEY:default}`, else `null`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `unknown` | — | — |

**Related:** [EnvRef](/reference/studio-sdk/utilities#envref)

## parseFieldPath

```ts theme={null}
function parseFieldPath(value: string): FieldSource | null
```

Recover a field source from a pure path expression, or `null` if it is not one.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `value` | `string` | — | — |

**Related:** [FieldSource](/reference/studio-sdk/utilities#fieldsource)

## parseTemplateCall

```ts theme={null}
function parseTemplateCall(expr: string): { adapter: string; callName: string } | null
```

Recover `{ callName, adapter }` from a `tjq_<callName>(<adapter>)` call, or `null`
otherwise. `callName` is the RAW jq identifier — NEVER split here (a jq name may carry
its own `__` past the template boundary); resolve it to a catalog ref with
`resolveCallName`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `expr` | `string` | — | — |

## resolveCallName

```ts theme={null}
function resolveCallName(
  callName: string,
  catalog: readonly BindingTemplateOption[],
): string | null
```

Resolve a jq call name (`enc(template)__name`, or a bare `name`) back to the catalog
ref, driven by the catalog — never by string splitting, since a jq name may carry its
own `__` past the template boundary and `enc` maps `-`→`_`. Under the template-slug
invariant (no consecutive/trailing hyphens ⇒ `enc(template)` has no `__` and no
trailing `_`) the FIRST `__` is the one true boundary, so the longest encoded-template
prefix whose remainder is a jq the template declares is the unique qualified match;
failing that, a bare name a single template declares. `null` when nothing claims it.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `callName` | `string` | — | — |
| `catalog` | `readonly BindingTemplateOption[]` | — | — |

**Related:** [BindingTemplateOption](/reference/studio-sdk/utilities#bindingtemplateoption)

## resolveTemplateJq

```ts theme={null}
function resolveTemplateJq(
  templateNames: readonly string[],
  catalog: readonly BindingTemplateOption[],
  purpose?: "input" | "update",
): ResolvedTemplateJq[]
```

Every template jq the given attached templates offer for a purpose (or all
purposes when `purpose` is omitted), each carrying the reference a binding stores.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `templateNames` | `readonly string[]` | — | — |
| `catalog` | `readonly BindingTemplateOption[]` | — | — |
| `purpose` *(optional)* | `"input" \| "update"` | — | — |

**Related:** [BindingTemplateOption](/reference/studio-sdk/utilities#bindingtemplateoption), [ResolvedTemplateJq](/reference/studio-sdk/utilities#resolvedtemplatejq)

## rowValueJq

```ts theme={null}
function rowValueJq(source: MappingSource): AdapterCompileResult
```

The jq fragment ONE row's value compiles to — the row's "show jq".

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `source` | `MappingSource` | — | — |

**Related:** [AdapterCompileResult](/reference/studio-sdk/utilities#adaptercompileresult), [MappingSource](/reference/studio-sdk/utilities#mappingsource)

## stateTemplatesKey

```ts theme={null}
const stateTemplatesKey: readonly ["states", "state-templates"]
```

The state-template document catalog (`GET /api/state-templates`). Read by the states
feature AND every state-binding door screen (the templates a binding attaches),
keyed here so the two never fetch the same catalog under diverging tuples.

## statesCatalogFromList

```ts theme={null}
function statesCatalogFromList(
  states: readonly ({ default_subject_kind: string; description: string; effective_schema: Record<string, unknown> | null; name: string; regimes: ({ path: string[]; regime: "single" | "free" | "composing" })[] | null; retention_days: number | null; schema?: Record<string, unknown> | { content?: string; id?: string; kwargs?: Record<string, unknown> }; subject_kinds: string[]; updated_at: string | null })[],
): BindingStateOption[]
```

The states catalog from `listStates()`; per-state attachments are resolved lazily elsewhere.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `states` | `readonly ({ default_subject_kind: string; description: string; effective_schema: Record<string, unknown> \| null; name: string; regimes: ({ path: string[]; regime: "single" \| "free" \| "composing" })[] \| null; retention_days: number \| null; schema?: Record<string, unknown> \| { content?: string; id?: string; kwargs?: Record<string, unknown> }; subject_kinds: string[]; updated_at: string \| null })[]` | — | — |

**Related:** [BindingStateOption](/reference/studio-sdk/utilities#bindingstateoption)

## statesListKey

```ts theme={null}
const statesListKey: readonly ["states", "list"]
```

The state catalog (`GET /api/states`). The states feature owns it, and every door
screen that hosts the state-binding editor (a preset, a route, a hook, a schedule)
reads the same catalog to populate the binding's state picker — so both key the one
authoritative tuple and a single fetch serves both.

## subMcpKey

```ts theme={null}
const subMcpKey: readonly ["sub-mcp"]
```

The discovered sub-MCP mounts (`GET /api/sub-mcp`). The settings feature reads
this map (its scope mapper lists the mounts) while the manifest feature owns the
create/delete controls that mutate it; both must key and invalidate the exact
same tuple, so it lives here rather than as a literal duplicated across the two
features (which cannot import each other).

## templatedTextCatalog

```ts theme={null}
function templatedTextCatalog(
  storage: StoragePresenceQueryLike,
  templates: TemplateNamesQueryLike,
): TemplatedTextCatalog
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `storage` | `StoragePresenceQueryLike` | — | — |
| `templates` | `TemplateNamesQueryLike` | — | — |

**Related:** [StoragePresenceQueryLike](/reference/studio-sdk/utilities#storagepresencequerylike), [TemplateNamesQueryLike](/reference/studio-sdk/utilities#templatenamesquerylike), [TemplatedTextCatalog](/reference/studio-sdk/utilities#templatedtextcatalog)

## templatesCatalogFromList

```ts theme={null}
function templatesCatalogFromList(
  items: readonly ({ attached_to: number; declarations: { check: { content?: string; id?: string; kwargs?: Record<string, unknown> } | null; schema: z.ZodRecord<z.ZodString, z.ZodUnknown> } | null; description: string; kind: "state-template"; name: string; parameters: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{ default: z.ZodOptional<z.ZodUnknown>; schema: z.ZodRecord<z.ZodString, z.ZodUnknown> }, z.core.$strict>>>; reconcile: { close: { content?: string; id?: string; kwargs?: Record<string, unknown> }; orphans: { content?: string; id?: string; kwargs?: Record<string, unknown> }; resolutions: { content?: string; id?: string; kwargs?: Record<string, unknown> } } | null; regimes: ({ path: string[]; regime: "single" | "free" | "composing" })[]; schema?: Record<string, unknown> | { content?: string; id?: string; kwargs?: Record<string, unknown> }; shipped_default: boolean; template_jq: Record<string, { description: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> }; params: string[]; purpose: "input" | "update"; reads: string[][]; writes: string[][] }> | null; trace?: { enabled: boolean } })[],
): BindingTemplateOption[]
```

The template catalog (with each template's template jq) from `listStateTemplates()`.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `items` | `readonly ({ attached_to: number; declarations: { check: { content?: string; id?: string; kwargs?: Record<string, unknown> } \| null; schema: z.ZodRecord<z.ZodString, z.ZodUnknown> } \| null; description: string; kind: "state-template"; name: string; parameters: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{ default: z.ZodOptional<z.ZodUnknown>; schema: z.ZodRecord<z.ZodString, z.ZodUnknown> }, z.core.$strict>>>; reconcile: { close: { content?: string; id?: string; kwargs?: Record<string, unknown> }; orphans: { content?: string; id?: string; kwargs?: Record<string, unknown> }; resolutions: { content?: string; id?: string; kwargs?: Record<string, unknown> } } \| null; regimes: ({ path: string[]; regime: "single" \| "free" \| "composing" })[]; schema?: Record<string, unknown> \| { content?: string; id?: string; kwargs?: Record<string, unknown> }; shipped_default: boolean; template_jq: Record<string, { description: string; jq: { content?: string; id?: string; kwargs?: Record<string, unknown> }; params: string[]; purpose: "input" \| "update"; reads: string[][]; writes: string[][] }> \| null; trace?: { enabled: boolean } })[]` | — | — |

**Related:** [BindingTemplateOption](/reference/studio-sdk/utilities#bindingtemplateoption)

## tokensPayloadKey

```ts theme={null}
const tokensPayloadKey: readonly ["auth-tokens-payload"]
```

The api-key payloads; read by settings AND the hooks execution-key picker.

## toolBadgesByName

```ts theme={null}
function toolBadgesByName(
  tagEntries: readonly ({ badges: string[]; hidden: boolean; name: string; schedulable: boolean; tags: string[] })[],
  overlayRows: readonly ({ badges: string[]; display_name: string | null; folder_id: string | null; hidden: boolean | null; tags: string[]; tool_name: string })[],
): Readonly<Record<string, readonly string[]>>
```

The raw-name → merged-badges map a tool picker reads to render the SELECTED tool's
badges, from the native declarations (`listToolTags`) merged with the tool\_meta
overlay (`listToolMeta`) — the SAME union the tools list shows. Only tools with at
least one badge appear; a name with none is simply absent (the picker shows no
chips). Both sources' names are walked, so an overlay row that badges a tool
carrying no native tag entry is still surfaced.

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `tagEntries` | `readonly ({ badges: string[]; hidden: boolean; name: string; schedulable: boolean; tags: string[] })[]` | — | — |
| `overlayRows` | `readonly ({ badges: string[]; display_name: string \| null; folder_id: string \| null; hidden: boolean \| null; tags: string[]; tool_name: string })[]` | — | — |

## toolsListKey

```ts theme={null}
const toolsListKey: readonly ["tools"]
```

The registered-tool master list (`GET /api/tools`).


# Self-hosted
Source: https://docs.tai42.ai/self-hosted/index

Run tai from the official container image — one signed, scanned, multi-arch image plus a Compose bundle.

Run tai on your own infrastructure from the official container image. One image
plays every server role; a Compose bundle deploys it, and the
release pipeline signs and scans every artifact it publishes.

> **[Quickstart](/self-hosted/quickstart)**
>
> Deploy the Compose bundle against the official image.

> **[Upgrades](/self-hosted/upgrades)**
>
> Pull a new tag, run the migrations, recreate the app services.

> **[Verify artifacts](/self-hosted/verify)**
>
> Check cosign signatures and image digests.

> **[Web stacks](/self-hosted/web-stacks)**
>
> Run the marketplace and website images.

> **[Ops notes](/self-hosted/ops)**
>
> Reverse proxies, backups, and health probes.

## The image

`docker.io/tai42/tai` is the official image, mirrored at `ghcr.io/tai42ai/tai`.
It is one minimal-core image that runs every deployment role from a single
entrypoint (`tai`): the HTTP server, the task backend worker, and the metrics
reader. What a container becomes is chosen by its command and its
[manifest](/concepts/manifest), not by a different image per role.

| Property | Value |
| - | - |
| Registries | `docker.io/tai42/tai` and `ghcr.io/tai42ai/tai` (identical content) |
| Architectures | `linux/amd64` and `linux/arm64` (one multi-arch manifest list per tag) |
| Signed | cosign keyless signature on the manifest-list digest in **both** registries |
| Scanned | Trivy gates the build — a fixable critical/high CVE fails the release before any push |
| Attested | SBOM and provenance attestations attached in-registry; a CycloneDX SBOM is attached to each GitHub Release |

The three long-lived processes all come out of this one image:

| Process | Command | Role |
| - | - | - |
| serve | `tai serve` | HTTP API, the MCP endpoint, and the [Studio](/studio) SPA, on one origin |
| backend worker | `tai backend worker` | queued, scheduled, and agent work |
| metrics | `tai metrics` | the Prometheus multiprocess endpoint |

### Tags

The release publishes a semver fan-out — `X.Y.Z`, `X.Y`, `X`, and `latest` — for
a stable release; a prerelease publishes its exact version tag only and leaves
the moving tags on the last stable image. **Pin an exact `X.Y.Z` tag in
production**; `latest` moves under you.

## Minimum to run

* **A default database connection.** `POSTGRES_PASSWORD` has no default — the
  stack refuses to start until it is set. It feeds the `default` database every
  core Postgres store binds to (`TAI_DATABASE_DEFAULT_PG_*`).
* **A Redis URL** once any of these is on: access control, a registered task
  backend, more than one server worker, or config served from a non-`file`
  provider. The Compose bundle registers the arq backend and runs two workers,
  so it presets `TAI_BUS_REDIS_URL` (and the per-feature Redis URLs) for you.
  The agents layer's default checkpoint store and LLM store need that Redis to
  carry the JSON and search modules (Redis 8 ships both); the Compose bundle's
  Redis does.
* **Everything else has a working default** — see the
  [settings reference](/reference/settings) for every variable and its default.

## What the image bundles

The image is the **minimal core**: the platform layers, the agents layer, and
the baked reference providers — local storage, the arq task backend, the Redis
identity (API-key) provider, and both sandbox providers — and the built Studio
SPA. The bundled package set is exactly:

| Package | What it is |
| - | - |
| `tai42-contract` | the contract layer every plugin registers through |
| `tai42-kit` | shared clients, settings, and transport helpers |
| `tai42-cli` | the `tai` command — the remote client over the server's HTTP API |
| `tai42-skeleton` | the runtime — the server, plus the local and runtime commands it adds to `tai` (with the `toolbox` and `files` extras) |
| `tai42-toolbox` | the standard toolbox tools and composition extensions |
| `tai42-agents` | the agents layer |
| `tai42-storage-local` | the local-disk storage provider |
| `tai42-backend-arq` | the arq (Redis-only) task backend |
| `tai42-identity-redis` | the Redis-backed API-key identity provider |
| `tai42-sandbox-docker` | the container-isolated sandbox provider (weightless; the sandbox stays off until a manifest selects it) |
| `tai42-sandbox-local` | the direct-on-host sandbox provider (weightless; the sandbox stays off until a manifest selects it) |

The bundle ships a value for these bundled-plugin variables (a compose-file or
env-template value; a value the operator must fill is shown as a placeholder):

| Bundled plugin | Variable | Value the bundle ships |
| - | - | - |
| `tai42-backend-arq` | `ARQ_REDIS_URL` | `redis://redis:6379/0` |
| `tai42-sandbox-docker` | `SANDBOX_DOCKER_HOST` | `tcp://sandbox-engine:2376` |
| `tai42-sandbox-docker` | `SANDBOX_DOCKER_READINESS_PROBE_ENABLED` | `1` |
| `tai42-sandbox-local` | `SANDBOX_LOCAL_ROOT` | `/var/lib/tai-sandbox-local` |
| `tai42-agents` | `TAI_AGENTS_CLAUDE_SESSION_IMAGE` | `docker.io/tai42/tai-sandbox-claude-code@<digest>` |
| `tai42-agents` | `TAI_AGENTS_LANGCHAIN_DEEP_SESSION_IMAGE` | `docker.io/tai42/tai-sandbox-exec@<digest>` |
| `tai42-agents` | `TAI_AGENTS_CLAUDE_API_KEY` | `<set by operator>` |

The two `tai42-agents` session images ship as digest placeholders the operator
replaces with the released digests, and the operator sets exactly one of
`TAI_AGENTS_CLAUDE_API_KEY` or the commented `TAI_AGENTS_CLAUDE_OAUTH_TOKEN` (the
bundle ships neither). `tai42-storage-local`
writes under `STORAGE_LOCAL_ROOT_PATH`, which the image sets to `/app/templates`
(the provider has no default root and refuses every call until it is set); the
bundle's example manifest selects
the provider (`storage_module: tai42_storage_local`) and backs `/app/templates`
with the `tai-storage-local-data` named volume, so stored files survive a
container recreation. `tai42-identity-redis` presets nothing — it stays off until
a manifest names it, then reads the shared `TAI_DEFAULT_REDIS_URL`. The two sandbox
providers stay off until a manifest names one (`sandbox_module`); the variables
above apply once a provider is selected. The bundle turns the docker sandbox's
egress-firewall readiness probe on for the session-creating services
(`SANDBOX_DOCKER_READINESS_PROBE_ENABLED` on serve and backend), which has no
effect until that provider is active.

Every other plugin — the channels, the S3/GitHub storages, the celery/rq
backends, the connectors, the webhook verifiers, monitoring, accounts, and the
extra tools — is **not** baked in. Add the ones a deployment needs at runtime
through the [marketplace](/concepts/marketplace) or by
[baking them into a derived image](/operate#add-plugins). See
[the layering](/concepts/layering) for what each layer contains.

The image pins its core versions as a pip/uv constraints file
(`/opt/tai/constraints.txt`, wired through `PIP_CONSTRAINT`/`UV_CONSTRAINT`), so any
install that would move a core package off the image's version is refused by the
resolver rather than silently downgraded or upgraded; the venv is root-owned, so a hand or
derived-image install into it runs as root (`USER root`, or `docker exec -u 0`),
while a marketplace install lands in its own prefix.

> [!NOTE]
>
> Runtime-installed plugins live in the server's plugin prefix, not in the image.
> An image upgrade replaces the core but **does not** update a runtime-installed
> plugin — see [Upgrades](/self-hosted/upgrades#runtime-installed-plugins).

## Reaching a service on the Compose network

A tool that fetches a URL server-side — the toolbox
[`request`](/guides/standard-toolbox) tool, or any tool you write — passes tai's
URL guard before it connects. The guard is on by default and refuses private,
loopback, and link-local addresses. Every service in the Compose bundle rides
the `default` network, which takes a private Docker subnet, so such a tool
cannot reach another Compose service until you allow that subnet in.

To let a tool reach a service on the Compose network, set
[`TAI_URL_GUARD_ALLOW_CIDRS`](/reference/settings#urlguardsettings) to that
network's CIDR. It is an explicit opt-in — the guard blocks that range until you
name it, and it bypasses nothing on its own.

A run that only needs to reach the platform itself opens no network at all. The
built-in door tools
[`send_conversation_message` and `send_conversation_event`](/reference/conversation-bridge)
submit a message or event back into a conversation in-process — no key, no HTTP
request, and no URL guard.


# Ops notes
Source: https://docs.tai42.ai/self-hosted/ops

Reverse proxies, backups, and health probes for a self-hosted server.

Operational caveats a self-hosted deployment runs into. Each links to the deeper
platform page where it applies.

## Reverse proxy in front

`serve` speaks plain HTTP on its published port and puts nothing in front of it —
terminate TLS at your own reverse proxy or load balancer and forward to that
port. The Studio and the `/api` surface share one origin, so there is nothing to
split.

> [!WARNING]
>
> Recreating a container gives it a **new IP**. A name-based reverse proxy that
> resolves the upstream once at startup keeps forwarding to the old address after
> an upgrade or restart and starts failing. Re-resolve on each request, or reload
> the proxy when the stack is recreated. On the Compose network use the service
> name (`serve`), not a captured IP.

> [!WARNING]
>
> Some record identifiers carry an **encoded slash** (`%2F`) in the URL path. A
> proxy or gateway that normalizes paths — or that decodes, rewrites, or redirects
> encoded slashes — corrupts those paths, and the requests fail. Configure the
> proxy in front of `serve` to pass `%2F` through unchanged: do not normalize,
> decode, or redirect an encoded slash in the request path.

Some features need the public origin spelled out rather than inferred:
[connectors](/concepts/connectors) accept an OAuth redirect only when its origin
is in `CONNECTORS_REDIRECT_URI_ALLOWLIST`. See [TLS and the front
door](/operate#tls-and-the-front-door).

## Backups

The application state lives in Postgres and Redis, and in the two persistent
mounts (the config directory and the plugin prefix). Back up all of them.

* **Datastores** — snapshot the Postgres and Redis volumes on your own schedule;
  the image holds no state.
* **Stored platform state** — the runtime exports its own state (access-control
  policies, presets, and whatever else plugins register) as a backup document
  with `tai backup export`. See [Back up and restore](/operate/backup-and-restore).
* **Config** — keep `config/manifest.yml` and the plugin prefix, so a restored
  server boots with the same manifest and the same runtime-installed plugins.

## Schema migrations

`tai db migrate` applies every pending file across all components; `tai db status`
reports each component's applied/pending/checksum verdict without changing
anything, and exits non-zero when any is out of date — so it doubles as a
pre-deploy gate:

```bash theme={null}
tai db status
```

Both commands connect through each component's bound [named
database](/concepts/config-and-secrets#named-databases) and its **admin**
identity — `TAI_DATABASE_<NAME>_PG_ADMIN_*`, the DDL-privileged role, falling back
to that database's runtime role when unset — distinct from the app's runtime store
role. The chain model, the [`tai_schema_history`](/concepts/marketplace#the-migrations-contract)
source of truth, the forward-only rule, and the checksum-immutability constraint
are the [migrations contract](/concepts/marketplace#the-migrations-contract).
Because recovery is a restore-and-re-migrate, never a rollback, snapshot the
database before any schema-carrying upgrade — see [Back up and
restore](/operate/backup-and-restore#recovering-from-a-bad-migration).

## Health probes

The server exposes unauthenticated `/health` (liveness) and `/ready` (every wired
store, pinged under a 5s budget) routes for orchestrators and load balancers —
served public by the app's own route-level declaration, so no allowlisting. The
bundle's serve healthcheck already probes `/health`. `/ready` additionally fails
(and the process exits for a supervised restart) when one of the server's
long-lived background tasks stops unexpectedly, naming the stopped task in its
response. The full probe semantics are
[Liveness and readiness](/operate/deploy#liveness-and-readiness).

## Observability

`tai metrics` serves the Prometheus multiprocess endpoint on its own port and
reads the metrics directory the app process writes, so it runs beside that
process on the same filesystem — its own service on serve's volume in the
Compose bundle, a sidecar container in the same pod on Kubernetes. Query traces
and aggregate metrics with `tai obs`. See [Observe](/operate/observe).

## See also

* [Deploy](/operate/deploy) — transports, workers, access control at deploy.
* [Manage a fleet](/operate/manage-a-fleet) — the worker census and fleet-wide operations.


# Quickstart
Source: https://docs.tai42.ai/self-hosted/quickstart

Deploy the Compose bundle against the official image.

Bring up the whole stack — serve, the backend worker, metrics, Postgres, and
Redis 8 — with the Compose bundle from
[`tai-distribution`](https://github.com/tai42ai/tai-distribution), running the
official image. The bundle needs Docker Compose 2.20 or newer.

## Boot the bundle

**1. Get the bundle**

```bash theme={null}
git clone https://github.com/tai42ai/tai-distribution
cd tai-distribution/compose
```

**2. Pin the image and set the secrets**

```bash theme={null}
cp .env.example .env
```

Set `POSTGRES_PASSWORD` (it has no default — Compose refuses to start until
it is set), and pin the image to a release rather than running `latest`:

```bash TAI_VERSION in .env theme={null}
TAI_VERSION=1.6.33   # pin to the release you are deploying
```

**3. Create the config directory**

```bash theme={null}
mkdir -p config
cp manifest.example.yml config/manifest.yml
touch config/.env
```

`config/` bind-mounts at `/app`, so `config/manifest.yml` is the
[manifest](/concepts/manifest) the runtime loads and `config/.env` is the
app-side environment. Create `config/.env` even when it is empty — the
config-reload path treats a missing file as an error.

**4. Start it**

```bash theme={null}
docker compose up -d
```

A one-shot `db-migrate` runs `tai db migrate` first; serve and backend wait
for it before they start. Only serve publishes a port
(`${TAI_SERVE_PORT:-8000}`) — Postgres and Redis stay on the Compose network.

> [!WARNING]
>
> `.env.example` ships `ACCESS_CONTROL_ENABLE=false` — the auth-free quickstart
> shape, every route open. Turn it on before anything but a laptop, and register an
> identity provider in the same change: with access control on and no provider, the
> runtime refuses to boot. See [Turn on access control](/operate#turn-on-access-control).

## The persistent mounts

Three paths a real deployment must keep across a container recreation, each
located by an env var the server reads:

| Mount | Env var | Holds |
| - | - | - |
| Config directory | `TAI_MANIFEST_PATH` (in `TAI_CONFIG_DIR_PATH`) | the manifest — the **registration** of every runtime-installed plugin |
| Plugin prefix | `TAI_PLUGINS_PREFIX` | the installed plugin **code** |
| Local storage data | `STORAGE_LOCAL_ROOT_PATH` (set by the image to `/app/templates`) | files the local storage provider serves |

The bundle bind-mounts `config/` for the first and backs `/app/templates` with
the `tai-storage-local-data` named volume for the third. Give the plugin prefix
its own persistent volume the same way, or a [marketplace](/concepts/marketplace)
install lands in the image's ephemeral venv and is lost when the container is
replaced. Persist all three, or a recreated container loses stored files or boots
with the code and its registration out of sync. The bundled Postgres and Redis
keep their own named data volumes.

See [Add plugins](/operate#add-plugins) for the two ways a deployment installs
plugins onto these mounts.

## Profiles

The core stack is arq-on-Redis, and the example manifest selects local storage
(`storage_module: tai42_storage_local`). Four opt-in profiles add
infrastructure. `celery`, `minio`, and `monitoring` serve plugins that are **not** in
the minimal image — add the plugin (a derived image or a marketplace install) before
enabling its profile. `sandbox` serves the Docker sandbox provider, which the image
already ships. The core Redis is Redis 8, so the default checkpoint store and LLM store
run on it with no profile:

| Profile | Adds | For |
| - | - | - |
| `celery` | a RabbitMQ broker | the celery task backend (`tai42-backend-celery`) |
| `minio` | MinIO + a bucket-init one-shot | the S3 storage provider (`tai42-storage-s3`) |
| `sandbox` | a rootless Docker engine (`sandbox-engine`) | the Docker sandbox provider (`tai42-sandbox-docker`) |
| `monitoring` | an OpenTelemetry collector | monitoring with Langfuse (`tai42-monitoring-langfuse`): serve and the worker export their records to it, and it sends them to Langfuse |

```bash theme={null}
docker compose --profile minio up -d
```

Langfuse itself runs as its own stack from `compose/langfuse/`. Its `langfuse-web`
joins the core stack's `<project>_monitoring` network (`tai_monitoring` under the
default project name; `TAI_CORE_PROJECT` in `compose/langfuse/.env` names the core
project), so bring the core stack up first. The containers then reach it at
`http://langfuse-web:3000` (inside a container, `localhost` is that container). Set
that address as `LANGFUSE_HOST` in two places:

* `config/.env`, with `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY`: the plugin's reads.
* `.env`, with `OTEL_COLLECTOR_LANGFUSE_AUTH` (base64 of `<public key>:<secret key>`):
  the collector's sends.

The network belongs to one core stack, so each core stack on a host sends to its own
collector and its own Langfuse only. For several core stacks on one host, run one
Langfuse stack per core stack, each with its own project name (`-p`), its own
`LANGFUSE_WEB_PORT` and its `TAI_CORE_PROJECT`.

The core stack owns the network. If the core stack is taken `down` and up again while
`langfuse-web` is stopped, the network it pointed at is gone and it refuses to start
(`network … not found`). Recreate it:

```bash theme={null}
docker compose -f compose/langfuse/docker-compose.yml up -d --force-recreate langfuse-web
```

See [Monitoring with Langfuse](/plugins/tai42/monitoring-langfuse).

## Build the image from source (dev only)

For running the stack against uncommitted local changes,
`compose/docker-compose.local.yml` layers a `SOURCE=local` build onto every app
service, building from sibling checkouts instead of pulling the release:

```bash theme={null}
# with every tai-* repo cloned beside tai-distribution
TAI_VERSION=local docker compose \
  -f docker-compose.yml -f docker-compose.local.yml up -d --build
```

> [!WARNING]
>
> The source build's `siblings` context is the parent of the checkouts, which can
> hold untracked secrets. Run it on a **local builder only** — never CI, never a
> shared registry. Production runs the official image.

## See also

* [Deploy](/operate/deploy) — transports, workers, and the serving modes.
* [Operate](/operate) — access control, plugin setup, and the fleet view.
* [Upgrades](/self-hosted/upgrades) — moving to a new image tag.


# Upgrades
Source: https://docs.tai42.ai/self-hosted/upgrades

Move to a new image tag: run the migrations, recreate the app services, leave the data untouched.

Upgrading is a tag change plus a migration run. A new image can carry pending
schema **migrations**; a one-shot runner applies the chain before the app
services start, and each container refuses to serve on an out-of-date database
(the [boot gate](#the-boot-gate)). The image carries no state, so the data
volumes are never touched — only the app containers are replaced.

## Upgrade the Compose bundle

**1. Snapshot the database first**

A migration rolls **forward** only — there are no down-migrations. Before an
upgrade that carries schema changes, take a Postgres snapshot (a managed
provider's point-in-time restore, or `pg_dump`) so a bad release is a restore
away. Recovery is restore-then-re-migrate, never a rollback.

**2. Pin the new tag**

Set `TAI_VERSION` in `.env` to the release you are moving to.

```bash TAI_VERSION in .env theme={null}
TAI_VERSION=1.6.33
```

**3. Pull it**

```bash theme={null}
docker compose pull
```

**4. Run the migrations**

```bash theme={null}
docker compose run --rm db-migrate
```

The one-shot `db-migrate` service runs `tai db migrate`, which applies every
pending migration across every component — the core chain and each installed
plugin that owns one — in order, recording each in the `tai_schema_history`
table. It is idempotent: a run with nothing pending reports so and exits `0`.
Preview a run first with `docker compose run --rm db-migrate db migrate --plan`,
which lists the pending files without touching the database.

**5. Recreate the app services only**

```bash theme={null}
docker compose up -d --no-deps serve backend metrics
```

`--no-deps` recreates the three app services against the new image without
restarting Postgres or Redis, so the datastores — and their volumes — stay
up.

> [!NOTE]
>
> Read the release notes before pinning. A release that needs a step beyond the
> migration run — a data backfill, a manual expand/contract cutover — names it.

## The boot gate

Each `serve` and `backend` container checks, once at startup, that every schema
chain its configured features and plugins own is fully applied. A pending
migration or a rewritten (checksum-mismatched) chain is a **loud refusal**, not a
half-migrated serve:

```text theme={null}
database schema is out of date — refusing to start: skeleton: 1 pending (0002_add_index.sql). Run 'tai db migrate' to apply the pending migrations, then restart.
```

The fix is the message: run the migration step above, then let the container
restart. If you recreate the app services before running `db-migrate`, they refuse
to boot with exactly this message — run the migrations and they come up. Running
`db-migrate` before the app services (the step order above) avoids the refusal
entirely.

## Runtime-installed plugins

An image upgrade replaces the **core** only. Plugins added at runtime through the
[marketplace](/concepts/marketplace) live in the server's plugin prefix
(`TAI_PLUGINS_PREFIX`), not in the image, so **they do not update with a new image
tag** — a freshly pinned image boots with the same plugin versions the prefix
already holds.

Update them as a step of their own, after the image upgrade:

```bash theme={null}
tai plugins upgrade --all
```

This resolves each installed plugin to the newest version compatible with the
core you are now running and installs it into the same persistent prefix. A
**router** or **middleware** plugin — and a channel's inbound webhook route — comes
live on the next reload / config-apply, not on a container restart: the epoch
rebuild that a reload runs re-imports the plugin package and its route-sibling
modules and re-registers the declared routes, so an upgraded router or middleware
is serving once that reload lands.

The image pins its own core versions as a pip/uv constraints file at
`/opt/tai/constraints.txt` and sets `PIP_CONSTRAINT`/`UV_CONSTRAINT` to it, so any
install — a marketplace install, `python -m pip install` by hand, or a derived
image's build step — that would move a core package (`tai42-contract`, `tai42-kit`,
`tai42-skeleton`, `tai42-cli`, or any other package the image ships) off the image's
version is refused by the resolver, never silently downgraded or upgraded. An
incompatible plugin fails loudly at install:

```text theme={null}
ERROR: Cannot install tai42-monitoring-langfuse==3.0.3 because these package versions have conflicting dependencies.
    The user requested (constraint) tai42-contract==14.0.0
ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts
```

The venv is root-owned, so a direct install into it runs as root — a derived image's
`USER root` build step, or `docker exec -u 0` into a running container. The
marketplace installer writes to its own `--prefix` and is unaffected. After a manual
or derived-image install, run `python -m pip check` to confirm the environment is
consistent.

> [!WARNING]
>
> A manifest-declared plugin that is incompatible with the new core — or otherwise
> cannot load — **aborts boot loudly**: the process exits naming the module, its
> kind, and the reason, rather than coming up missing a plugin the manifest asked
> for. Fix or update the plugin, point the manifest at a working one, or remove it
> from the manifest, then boot again. A plugin that cannot load during a live
> config reload aborts that reload instead: the previous generation keeps serving
> and the reload call returns the failure (a non-2xx naming the module, which `tai
>   config reload` prints before exiting non-zero). Keep the plugin prefix on
> persistent storage so the installed set survives the container recreation an
> upgrade performs.

## See also

* [Verify artifacts](/self-hosted/verify) — confirm the new tag before you run it.
* [Back up and restore](/operate/backup-and-restore) — capture state before an upgrade.


# Verify artifacts
Source: https://docs.tai42.ai/self-hosted/verify

Check the cosign signature and pin the image by digest before you run it.

Every release signs the image with a keyless cosign signature and
publishes an SBOM. Verify the signature before you run an artifact, and pin by
digest so the bits never change under a tag.

## Verify the image signature

The signature is keyless, made by the release workflow's GitHub OIDC identity.
Verify against that identity and issuer:

```bash theme={null}
cosign verify \
  --certificate-identity-regexp '^https://github.com/tai42ai/tai-distribution/\.github/workflows/release\.yml@refs/tags/v.*$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  docker.io/tai42/tai:1.6.33
```

The manifest-list digest is signed in **both** registries, so the same command
verifies `ghcr.io/tai42ai/tai:1.6.33`. A missing or mismatched signature exits
non-zero.

> [!NOTE]
>
> The signature is attached to the **manifest-list digest**, not to a tag. cosign
> resolves the tag to that digest before it checks, so verifying a moving tag
> (`latest`, `X.Y`) checks whatever image the tag currently points at.

## Pin by digest

A tag can be re-pointed; a digest cannot. Read the current manifest-list digest
and run that exact reference:

```bash theme={null}
docker buildx imagetools inspect docker.io/tai42/tai:1.6.33 \
  --format '{{ .Manifest.Digest }}'
```

```bash TAI_VERSION in .env theme={null}
TAI_VERSION=1.6.33@sha256:<digest>
```

The multi-arch manifest list carries both `linux/amd64` and `linux/arm64`;
`imagetools inspect` with no `--format` lists the per-arch entries.

## SBOM and provenance

The build attaches SBOM and provenance attestations to the image in-registry,
and each GitHub Release carries a CycloneDX SBOM (`sbom.cdx.json`) for the
released multi-arch image. Use them to feed a vulnerability scanner or a
supply-chain policy.

## See also

* [Upgrades](/self-hosted/upgrades) — verify a new tag before rolling to it.
* [The image](/self-hosted#the-image) — what the release pipeline signs and scans.


# Web stacks
Source: https://docs.tai42.ai/self-hosted/web-stacks

Run the optional marketplace and website images.

Three optional web services ship their own images on GHCR, separate from the core
`tai` image. Run them only if you want to self-host the marketplace registry, its
browser UI, or the public website — none is required to run a server.

| Image | Repository | Serves |
| - | - | - |
| `ghcr.io/tai42ai/tai-marketplace` | [tai-marketplace](https://github.com/tai42ai/tai-marketplace) | the marketplace registry service |
| `ghcr.io/tai42ai/tai-marketplace-web` | [tai-marketplace-web](https://github.com/tai42ai/tai-marketplace-web) | the marketplace browser UI |
| `ghcr.io/tai42ai/tai-website` | [tai-website](https://github.com/tai42ai/tai-website) | the public marketing site |

## Tags and builds

Each image is built and pushed on every push to `main`, tagged both `:latest` and
`:<sha>` (the commit SHA). Pin the `:<sha>` of a known-good commit rather than
`:latest`. The website image builds only after its own type-check and build pass,
so a tree that fails them never publishes.

> [!NOTE]
>
> These images are `linux/amd64` only — unlike the multi-arch core `tai` image —
> and follow their repository's visibility on GHCR. A private repository's image
> needs a registry login to pull.

## Run one

```bash theme={null}
docker run --rm -p 8080:80 ghcr.io/tai42ai/tai-website:latest
```

Each image reads its own configuration; consult the service repository for the
environment it expects and the port it binds. The marketplace registry service
backs the [marketplace](/concepts/marketplace) install flow — a server points at
it to browse and install plugins.

## See also

* [Marketplace](/marketplace) — what the registry serves and how a server uses it.
* [Quickstart](/self-hosted/quickstart) — the core stack these sit beside.


# Admin console & live ops
Source: https://docs.tai42.ai/studio/admin-console

Watch a server's health, read its settings, and drive live operations from the browser.

The Studio is also the live operations console for a server. You confirm it is
healthy, read its configuration, and drive
[live operations](/concepts/live-operations) — reloading a tool, updating the
manifest, or removing a capability — without a restart and without leaving the
browser.

## Health

The System screen reads the server's liveness probe. A green `Healthy` badge
confirms the server is up and answering. The demo instance below shows a
populated `Healthy` badge.

![The System screen showing a 'Healthy' badge from the server's liveness probe.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/system-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=a5ea4fe052af61a906dbce8c3daf1fce)

The System screen: a populated 'Healthy' badge from the server's liveness probe.

## The kinds table

The System screen also reads the server's **kinds** summary — the plugin kinds
the server knows about and, for each, whether it is **active** (a provider is
configured and running), running on a **default** (the built-in fallback is in
use), or **off** (the kind is not configured). It is the fastest way to confirm
which providers a running server actually resolved — for example, which
[identity and accounts](/concepts/accounts) providers the configured
[auth-provider](/concepts/access-control) chain brought up. The same summary is
served at `GET /api/system/kinds` and printed in the server's startup log — see
[live operations](/concepts/live-operations#the-kinds-summary).

![The System kinds table listing plugin kinds with active, default, or off status.](https://mintcdn.com/tai42/svAMgtenosCg9O5X/images/studio/system-kinds-light.png?fit=max\&auto=format\&n=svAMgtenosCg9O5X\&q=85\&s=de3d865ad7eed7b2447a92546f730c89)

The System screen's kinds table: each known plugin kind with its active, default, or off status.

## Members

**Administration › Members** is the Studio-core surface for a server's **human
accounts**. It lists people and pending invitations aggregated across every
configured [accounts](/concepts/accounts) provider — read through the
accounts-provider contract, so a provider needs no bespoke Studio page to appear
here. Each row carries an opaque routing handle back to the provider that owns it.

The page performs each provider's own declared [member actions](/concepts/member-actions) —
invite a person, change a role or access, remove a member, send a login link,
cancel an invitation — through a single generic **invoke** door. The page renders
page buttons and per-row menu items from the provider's action declarations and
reads no field of any action's input or result; a provider adds or changes an
action by changing its declaration alone. The role picker reflects the current
editable role set: the seeded admin/editor/viewer plus any role an admin has
created with [`tai roles`](/reference/cli/roles).

The page governs only the `usr-*` human principals. Machine keys are managed on
the [API keys](/studio/api-keys) surface, and a principal provisioned directly
through the raw [access-control](/concepts/access-control) policy routes is
governed there — see the
[principal-type split](/concepts/accounts#what-the-members-page-governs).

![The Members page listing human accounts and pending invitations with member-action controls.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/members-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=a7157bd3b28b9016dbdc7ebaf27c26d4)

The Members page: human accounts and pending invitations aggregated across every configured accounts provider, with the provider-declared member actions.

> [!NOTE]
>
> The actions a row offers come from the accounts provider that owns it, declared
> as data the Members page renders and routes generically — see
> [member actions](/concepts/member-actions).

## The operations dashboard

The Dashboard summarises the server's [monitoring](/concepts/live-operations)
backend — total runs, cost, latency, and token counts over a time range, with a
per-model breakdown and a trend chart. It answers "what has this server been
doing" at a glance. The demo instance below is populated from a monitoring
backend seeded with example runs, so the summary tiles, trend chart, and
per-model breakdown show representative data. With no monitoring backend
registered, the Dashboard renders a clean empty state instead.

The per-model breakdown distinguishes three cases: it shows the bars when
per-model data is available, a plain empty state when the range holds no
per-model activity, and a distinct "Per-model breakdown is unavailable for this
range." notice when the per-model figures could not be computed — so an
unavailable breakdown is never mistaken for an idle one.

![The observability Dashboard with summary tiles and a trend chart.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/dashboard-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=4197ce90969ac8f9f4fbc31094ad73fc)

The observability Dashboard: run, cost, latency, and token summaries.

![The Dashboard with the per-model breakdown showing an unavailable-for-this-range notice.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/dashboard-by-model-unavailable-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=5bc5920a06dc2bea870aea2aa7e9c64b)

The Dashboard's per-model breakdown showing its unavailable notice when the figures could not be computed for the range.

## Settings and environment

The **Settings** and **Environment** tabs are the deployment's admin-owned config
store: the server's configuration mode, its settings schema, and the stored
environment values — one store holding the deployment's environment plus each
settings class's values, including deployment secrets such as the connector
encryption key. Each subsystem's settings — connector crypto, engine config, store
connections — surface as an editable form. Because that store is admin-owned, both
tabs are **admin-only**; an editor or viewer configures each feature through the
feature's own screen, never here — see
[user types and permissions](/concepts/permissions).

Saving the **Environment** tab writes the stored environment and reloads the fleet. A
change to a recycle-class setting — one whose pooled resource is built only when a
worker process starts — also rolls a worker recycle on a supervised deployment, and the
tab shows it under **Worker recycle**: one row per worker the roll reached, a recycled
worker joined onto its fresh life, and the worker that took the save recycling itself
after replying. A roll that stops says where and why, and the workers the server names
as still awaiting a respawn are listed as waiting for a restart; the **Apply profile**
report shows the same rows and the same list. On a bare deployment the same save is refused,
naming the key and the way out. See [reload classes](/concepts/config-and-secrets).

![The Environment tab's Worker recycle section listing two recycled backend workers and the serve worker recycling itself.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/settings-env-recycle-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=beda3b2f914a9b05ec070c281d986fc9)

The Environment tab after a save that rolled a worker recycle: the recycled workers on their fresh lives and the writer recycling itself.

![The Apply profile report with a stopped recycle: a recycled backend, a timed-out backend with its reason, and the restart list naming the workers still awaiting a respawn.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/profile-apply-recycle-stopped-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=7316a8da5a56ebc06f369e0df0ac0072)

A profile apply whose recycle stopped: the recycled worker, the worker it stopped at and why, and the workers still waiting for a restart.

Restoring a backup's `env` section on the **Backup** tab is the same env write. Its
import report lists the workers the server names as still awaiting a respawn, and
shows the section's **Worker recycle** rows when the restore rolled a recycle, with
where and why a stopped roll stopped. On a bare deployment the section's row carries
the same refusal, and nothing is stored.

![The Backup tab's import report for an env-section restore: the restart list naming the workers still awaiting a respawn and the Worker recycle rows with a stopped roll.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/backup-restore-recycle-stopped-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=4fa24270eecd4b15608d3b3a80b8c154)

A backup restore whose recycle stopped: the workers still waiting for a restart, then the recycled worker and the worker the roll stopped at.

The **API keys** tab on this screen is separate and **self-service**: any signed-in
user manages its own keys there, regardless of role. A key needs at least one scope or
a condition: the server refuses a key created with neither, and the **Create API key**
dialog shows its reason and keeps the form open.

![The Settings screen showing the server's configuration schema.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/settings-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=29c28b4fb0cb40766f0a6836a4ce77a1)

The Settings screen: the server's configuration mode and settings schema.

Below the keys, the same tab carries the **Access control** card: the scopes
mapper that decides which [scope](/concepts/access-control) covers which route.
Each scope is a zone listing the routes mapped to it, with a row to add a route
or a dynamic pattern by hand. **Unassigned** holds every route and sub-MCP mount
no scope covers yet, apart from the routes pinned public and the routes public by
their own declaration (both below). The **Public** zone, marked *no auth*, holds the routes
pinned public: they are served without API-key authentication or any scope
check, so it is not a scope. Drag a route onto a scope to map it, or onto the
Public zone to pin it public after a confirm step; the drag works from the
keyboard as well. The routes public by their own declaration are listed apart, under
**Public by declaration**, as plain chips you cannot drag: they are served without
API-key authentication whatever scope or pin they are given, so they are never
Unassigned and the server refuses to map them. The card shows only to a caller whose access reaches the
route, public-route and sub-MCP reads it is built from, which an admin always
does.

![The API keys tab's Access control card listing a scope with its route, the unassigned routes, and the Public zone.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/settings-access-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=988168ea8d82480367c74c5d8a130856)

The Access control card: a scope zone with its mapped route, the Unassigned routes, and the Public zone with its note.

## Live operations

Because the Studio drives the same `/api/*` surface as the
[`tai` CLI](/reference/cli/index), the management
[operations](/concepts/live-operations) are one run away. From the Tools screen
you invoke `reload_tool`, `remove_tool`, or `reload_config` — the
[live operations](/concepts/live-operations) — to reload a tool, drop one from
the live registry, or soft-restart the server in place. While a reload is in
flight, the API answers dispatch routes with a retriable `503` rather than
serving against a half-swapped registry.

> [!TIP]
>
> Anything the console does maps to an HTTP route and a CLI command. Reach for
> `tai mcp status` or `tai tools run` from a terminal when you want the same
> operation scripted.

See [live operations](/concepts/live-operations) for the management operations, and
the [CLI reference](/reference/cli/index) and
[HTTP API reference](/reference/api/index) for the routes behind each screen.


# API keys
Source: https://docs.tai42.ai/studio/api-keys

Sign in with a deployment API key and provision further keys from the Studio.

The Studio has no user database of its own. It authenticates with an API key
provisioned on the server, holds it in the browser, and sends it on every
request. The key is a full-access credential — treat it like a password.

## Signing in

The operator gets a full-privilege API key from the server — the owner key
[`tai setup`](/reference/cli/setup) prints once — then pastes it into the Studio
at [`/login`](/studio/login). The key is held in memory by
default; the **remember on this device** opt-in persists it to the browser
session so later navigations in the tab stay authenticated. When the server also
runs an [accounts](/concepts/accounts) provider, the key field sits behind the
*"Use an API key instead"* toggle on the [sign-in screen](/studio/login) — a
permanent fallback alongside human login.

> [!WARNING]
>
> The first key is a full-privilege credential, including tool execution. The
> Studio stores it client-side and sends it on every request — anyone with the key
> can run any tool on the server. Provision it out of band and treat it like a
> password.

## Keys are owned credentials

Once an [accounts](/concepts/accounts) provider is enabled, an API key is a
credential **owned** by an account rather than a free-standing secret. Ownership
changes what a key may hold and who may mint it:

* **A key can never out-scope its owner.** A key a non-admin mints is capped at a
  subset of its owner's own authority; a request for more is rejected at mint
  time. The cap is re-checked on every call, so if the owner's role is narrowed —
  or the owner is disabled — the key is attenuated with them on its next request.
* **Machine keys belong to a service principal.** For automation an admin creates
  a **service principal** — a non-human identity that holds keys but never logs in
  — and mints keys for it. That keeps the machine-to-machine path working while
  making an owner-bound key the default.
* **Key breadth is not admin.** A wide `["*"]` scope on a key does not make its
  holder an administrator of the key surface — it cannot list, edit, or revoke
  other owners' keys. Administration comes from the owner's role, never from a
  key's scope breadth.

## Provisioning more keys

Once signed in, the operator provisions further keys — full-privilege or scoped
— from the API-keys tab of the [Settings](/studio/admin-console#settings)
screen. That tab drives the server's `/api/auth` provisioning endpoints, so a
key minted in the Studio is the same key you could mint from the
[`tai keys`](/reference/cli/keys) CLI. When you mint a key, the create dialog
asks which principal owns it — yourself by default; an admin may pick a service
principal or create one inline.

The keys table carries a **Principal** column. Each row shows the principal that
owns the key — a human or a service principal, by kind and display name. A key
whose identity record was lost in a restore shows no principal and is marked
**orphaned** until the backup is re-imported. Ownership is the whole story of what
a key may hold and who may revoke it: an [owned key](/concepts/owned-keys) is
capped at a subset of its owner's authority and dies when its owner does. The
scope picker in the create dialog is capped to your own scopes, so a non-admin
cannot mint a key wider than itself.

> [!NOTE]
>
> Key provisioning and [access control](/concepts/access-control) run on the
> server's Redis-backed auth store. A server booted without access control accepts
> any key; a deployment that enforces it provisions keys and policies through this
> tab.

## Sharing a key by claim link

The create dialog is also where you hand a freshly minted key to another device
without ever putting the secret in a URL. The moment a key is created its raw
`sk-…` value is shown once, and the dialog offers a **Create claim link (QR)**
step: it turns that raw key into a one-time, short-lived
[claim link](/concepts/owned-keys#access-channels) and renders it as a QR code.
Scanning the code opens the [sign-in page](/studio/login) on the other device,
which exchanges the claim token for the key and signs in — the token rides the
URL fragment and burns on first use, so the credential never reaches a server
log.

![The API-keys create dialog showing a newly minted key and its QR claim-link step.](https://mintcdn.com/tai42/GIUznzIs4DR40qfu/images/studio/mint-claim-link-light.png?fit=max\&auto=format\&n=GIUznzIs4DR40qfu\&q=85\&s=d0c20e26cbb2e86613ea5d64e7b7a5ba)

The mint dialog's claim-link step: a freshly created key turned into a one-time QR claim link.

The claim-link step lives **only** in the mint dialog, never as a per-row action
on an existing key. Keys are stored hash-only — the server keeps a hash, never
the raw secret — so the plaintext key that a claim link must carry exists only in
the moment right after creation. There is no way to regenerate a claim link for a
key already in the table; mint a new key instead. See the
[owned-keys guide](/guides/owned-keys) for the full claim flow, including the
`tai auth claim` and CLI legs.

See [access control](/concepts/access-control) for the jq policy model behind
scoped keys, [owned keys](/concepts/owned-keys) for the delegation model, and the
[CLI reference](/reference/cli/keys) for provisioning keys from a terminal.


# Hooks and trigger links
Source: https://docs.tai42.ai/studio/hooks

Register a hook or mint a trigger link from the Studio, each bound to the execution key its fire runs as.

The Hooks screen drives the server's `/api/hooks` surface: it registers the
[hooks](/concepts/hooks) that fire a tool when an event arrives, binds a
[verifier](/concepts/triggers-and-webhooks) to a topic's public ingress door, and
mints [trigger links](/guides/fire-a-tool-from-a-webhook#trigger-links-qr) — public
QR URLs that fire a topic on a scan.

Every hook and every trigger link fires under a bound **execution key**: the api-key
identity the dispatch runs as. The picker is the same on both forms, and it is a
required field on each — a fire never runs as "nobody".

## Register a hook

The **Register hook** form names the topic to listen on and the tool to fire, then
binds the execution key that fire runs as. Name, topic, tool, and the execution key
are required; tool kwargs, a condition, and the [door-contract
jqs](/concepts/asking-the-caller#the-door-contract) (`start_expr`, `cancel_expr`,
`resume_expr`, `extras_expr`) are optional.

![The Studio Hooks page Register hook form with an execution-key picker selected.](https://mintcdn.com/tai42/iRrtHiBZz_SZ94au/images/studio/hooks-execution-key-light.png?fit=max\&auto=format\&n=iRrtHiBZz_SZ94au\&q=85\&s=307ab15d575eba617e66f5c087c2058c)

The Register hook form: the required execution-key picker binds the api-key identity each fire runs as.

The **Execution key** picker lists the api keys you may bind — your own identity or a
key you own; an admin may bind any. Each option shows the key's id, its description,
and its stable fingerprint. The fire runs **as** that key: every tool call it makes is
authorized against that key's live grants, so prefer a least-privilege service key
over a human's broad one. If no key is bindable the picker says so and points you at
the [API-keys tab](/studio/api-keys) to mint one first.

> [!NOTE]
>
> The binding is to the key's **fingerprint**, not just its id. Revoking the key kills
> every hook and link bound to it, and re-minting the same id does **not** revive the
> binding — the fingerprint changes, and a fire against the stale binding is denied, not
> run as the new key. See [owned keys](/concepts/owned-keys) for the delegation model.

> [!WARNING]
>
> The execution key is the whole authority a background fire runs on. A hook on a public
> topic fires for an anonymous caller, so the tool runs with exactly the key's grants and
> nothing more — bind the narrowest key that can do the job.

> [!NOTE]
>
> When the [tool-run store](/studio/running-tools) is configured, every hook and
> trigger-link fire is recorded like a background run — it lists in that tool's
> **Recent background runs** on the Tools screen, gettable by run id.

## Edit or remove a hook

Every registered hook lists in a table, and each row carries an **Edit** and a
**Delete** control. **Edit** opens the same form prefilled from that hook, titled
*Edit hook*; saving it is a true update over the register door — the button reads
**Save changes** — not a delete-and-recreate. A hook edited through an inline field
keeps any id-bound condition or door-contract jq it carried, so touching the topic or tool
never silently drops a gate you set by id. **Delete** opens a confirm dialog and
unregisters the hook by name; it is immediate and cannot be undone.

Binding a verifier to the topic is the adjacent **Bind verifier** form. It is
admin-only: a `hooks`-write role registers hooks and mints links but is fenced out of
setting or removing a topic's verifier. See
[fire a tool from a webhook](/guides/fire-a-tool-from-a-webhook) for the verifier flow.

## Mint a trigger link

A trigger link is a minted, public URL — `GET /trigger/<token>` — that fires a topic's
hooks on a bare request, printable as a QR code. The **Create trigger link** button
opens a dialog that takes the topic, an optional name, the execution key, an
**Also require an api key** toggle, an expiry (there is no default — choose one), and
optional tool params. On success the dialog renders the link's QR, shown once.

![The Studio Hooks page create-trigger-link dialog showing the generated QR code.](https://mintcdn.com/tai42/iRrtHiBZz_SZ94au/images/studio/hooks-trigger-link-light.png?fit=max\&auto=format\&n=iRrtHiBZz_SZ94au\&q=85\&s=9f020fe30e53850f18f6ba5270a7feab)

The Create trigger link dialog mints a public QR bound to an execution key; the QR is shown once.

The link binds its own execution key, independent of the hooks on the topic — each
fired hook still runs under **its own** bound key, while the link's key gates the
link's dispatch, so revoking that key kills the link. The **Also require an api key**
toggle adds a second gate: a caller must present an api key the route admits, beside
the token. It is enforced only where [access control](/concepts/access-control) is
enabled, and it never touches the topic's own `/universal_webhook/{topic}` door.

## The trigger-auth type

The trigger-links table lists each live link with its name, topic, bound execution
key, expiry, a params indicator, the token's hash prefix, and a **trigger-auth** cell
naming how that door reads. The value is server-derived from the live bindings, never
a stored flag:

| Trigger-auth | What admits a fire |
| - | - |
| Public | The topic's open `/universal_webhook/{topic}` door — no verifier, no token. |
| Verifier-signed | A verifier is bound; each delivery is signature-checked over its raw body. |
| QR token | The trigger link's token alone fires the topic. |
| QR token + api key | The token **and** an api key the gate admits, from the require-api-key toggle. |
| Out of service | The topic gained a verifier after minting; the link answers the uniform `404`. |

> [!WARNING]
>
> **Verified topics and trigger links are mutually exclusive.** Minting a link for a
> verifier-bound topic is refused, and a link whose topic later gains a verifier reads as
> **Out of service** and answers the uniform `404`. Treat the URL and its QR as a
> capability: anyone who holds it fires the topic for as long as the link lives.

Revoke a link from its row's revoke-confirm — immediate and durable, and a restored
backup cannot re-arm it. The token is shown once at creation and never stored, so a
listed link's QR is unrecoverable; to rotate a code, revoke and mint a new one.

See [hooks](/concepts/hooks) for the dispatch model,
[fire a tool from a webhook](/guides/fire-a-tool-from-a-webhook) for the full
binding-and-condition workflow from the CLI, and the
[`tai hooks` reference](/reference/cli/hooks) for the command surface.


# Studio
Source: https://docs.tai42.ai/studio/index

The desktop workbench for a running server — browse and exercise every surface from the browser.

The Studio is the visual workbench for a [server](/concepts/layering). It is a
React web UI that drives a running skeleton over its `/api/*` HTTP surface —
the same surface the [`tai` CLI](/reference/cli/index) calls — so anything you
do in the Studio you can also do from a terminal, and the reverse.

You browse and run [tools](/concepts/tools-and-extensions), apply
[extensions](/concepts/tools-and-extensions), author
[agents](/concepts/agents), render [templates](/concepts/storage-and-resources),
wire [event hooks](/concepts/hooks), watch [live
operations](/concepts/live-operations), install plugins from the
[marketplace](/marketplace/index), and provision API keys — all against one
self-hosted server.

![The Studio Tools screen listing the tools a server loaded.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/tools-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=0bee7e0b59692ae790dfb52b2f0c39ec)

The Studio, signed in on the Tools screen.

> **[The screens](/studio/screens)**
>
> A tour of every surface in the sidebar.

> **[Running tools](/studio/running-tools)**
>
> Synchronous runs versus detached background runs.

> **[Admin console & live ops](/studio/admin-console)**
>
> Health, settings, and live reloads.

> **[API keys](/studio/api-keys)**
>
> Sign in and provision keys for a deployment.

> **[Deploying the Studio](/operate/studio)**
>
> Serve the built app from the skeleton.

> **[Authoring a plugin](/studio/plugins)**
>
> Extend the shell with pages, panels, tabs, and nav entries.

> **[The jq editor](/studio/jq-editor)**
>
> jq-studio, the built-in visual jq editor — and a standalone library.

> **[Studio SDK reference](/reference/studio-sdk/index)**
>
> The plugin contract, hooks, and shared components.

> [!NOTE]
>
> The Studio has no user database of its own. It holds a deployment API key in the
> browser and sends it on every request — treat that key like a password. See
> [API keys](/studio/api-keys) for how sign-in works.

The screenshots throughout this section are captured from a live server booted
with the standard toolbox and the ready-made agents. Your own screens show the
tools, agents, and content your [manifest](/concepts/manifest) loads.


# The jq editor
Source: https://docs.tai42.ai/studio/jq-editor

The built-in visual jq editor — jq-studio, the open-source editor the Studio ships and any app can embed.

The Studio authors every jq expression through a visual editor: a small, editable
node graph that reads and writes the jq text on the wire. That editor is
**jq-studio** — an open-source, Apache-2.0 project. It is the Studio's built-in
editor, and it is a standalone library you can embed in any app of your own.

> [!NOTE]
>
> jq-studio is developed in the open at
> [github.com/tai42ai/jq-studio](https://github.com/tai42ai/jq-studio) and published
> to npm as [`@tai42/jq-studio`](https://www.npmjs.com/package/@tai42/jq-studio)
> (Apache-2.0). Its full component reference — the node vocabulary, the faithfulness
> guarantee, the theming contract, and the worker model — lives in that repository.
> This page covers how the Studio ships it and how to embed it; it does not restate
> the editor's own docs.

## Built in, everywhere

The [Studio SDK](/reference/studio-sdk/index) re-exports jq-studio's `JqField`
component and its declaration types. The Studio host does two things once, at the
shell level, so the editor is available to every field:

* it injects the Studio's design system through a **`PrimitivesProvider`**, so the
  editor renders in the host's own inputs, buttons, and tokens rather than a bundled
  look; and
* it installs the editor's **single evaluation worker** — one dedicated Web Worker
  shared across the page — so jq evaluation runs off the main thread for every field.

Because the host does this, a jq field never installs, registers, or gates the
editor. A [host field](/concepts/access-control#the-jq-policy) — an access-control
policy condition, a [hook](/concepts/hooks) condition or expression — offers the
canvas, a plugin field offers it, and a [flow's](/babelfish) jq field offers it,
all from the one re-export. There is no "is an editor present?" conditional and no
provider to opt into: the editor is part of the SDK, so a field that renders
`JqField` gets the visual canvas by construction.

## From the schema, with no code

A form does not have to name its jq fields at all. `SchemaForm` reads the
[`x-tai42-expression` annotation](/reference/api/index#expression-fields) the server
puts on a jq-typed string property and renders `JqField` for it — the resting
control plus the visual-editor door — carrying the annotation's label, blurb, input
keys, and Test-panel sample straight onto the field. So the server decides which
properties are expressions, and every form over that schema agrees.

The door is code-split. `SchemaForm` reaches the editor through a dynamic import
behind a lazy boundary, taken only when a field actually carries a well-formed
annotation — a form with no expression fields never pulls the editor, its worker, or
its wasm into the bundle. A malformed annotation, or a `language` this client does
not know, degrades silently to the ordinary text input rather than throwing.

## A standalone library

`@tai42/jq-studio` embeds in any React app the same way the Studio uses it: render
`JqField` inside a `PrimitivesProvider` that supplies your design-system primitives.

```tsx theme={null}
import { JqField, PrimitivesProvider } from '@tai42/jq-studio';

<PrimitivesProvider primitives={myPrimitives}>
  <JqField value={expr} onChange={setExpr} />
</PrimitivesProvider>;
```

The editor themes itself entirely through CSS custom properties. Every color it
paints reads from a **`--jq-*`** custom property, and it inherits light or dark from
the nearest ancestor carrying a **`data-theme`** attribute — so an app themes the
editor by setting those properties on a wrapper, with no editor configuration of its
own. See jq-studio's repository for the full `--jq-*` contract and the primitives
interface.

> [!NOTE]
>
> The editor evaluates jq in a **same-origin Web Worker** and enforces a
> terminate-on-deadline, so a runaway expression is killed rather than left to hang
> the tab. The worker is a real, same-origin file — a `'self'` worker with
> `'wasm-unsafe-eval'`, which is what a strict Content-Security-Policy permits. The
> Studio's own policy already allows it; an embedding app grants the same policy to run
> evaluation off-thread.

## See also

* [jq-studio on GitHub](https://github.com/tai42ai/jq-studio) — the editor's own repository and its component docs.
* [Author a Studio plugin](/studio/plugins#the-built-in-jq-editor) — how a plugin field renders the built-in editor, and the migration for plugins that used the old extension point.
* [Visual jq in flows](/babelfish/jq-editor) — how the flow editor authors jq with the same editor.
* [The jq policy](/concepts/access-control#the-jq-policy) — a host jq field the editor serves.


# Sign in
Source: https://docs.tai42.ai/studio/login

Sign in to the Studio with a login method, an invite, or an API key.

The Studio's sign-in screen is **metadata-driven**. It asks the server what
login methods it offers and renders exactly those — a password form, a sign-in
button, or both — with an API-key field always reachable as a fallback. A server
with no [accounts](/concepts/accounts) provider shows only the key field; a
server with one shows the human login flows its provider declares.

![The Studio sign-in screen rendering a login method with the API-key fallback.](https://mintcdn.com/tai42/dHRRA5iJWKLWv5ix/images/studio/login-light.png?fit=max\&auto=format\&n=dHRRA5iJWKLWv5ix\&q=85\&s=eb7e14e9f3c7b47af6848b2631b9441a)

The Studio sign-in screen at /login.

## Sign-in methods

The screen reads the server's public login-methods listing and draws one control
per declared method:

* A **credentials form** — the provider names the fields (for example email and
  password) and the route to post them to. Submitting mints a session and lands
  you on the screen you were headed for.
* A **redirect button** — a single button that navigates to a provider's sign-in
  flow (for example an OIDC authorize route). The provider owns the round trip;
  the callback returns a session.

Because the methods are data the provider declares, the login screen never
hard-codes a specific auth scheme — swapping or adding a provider changes what
the screen renders, with no Studio change.

## Setup

On a fresh deployment no principal exists yet, so the login listing reports
`needs_setup` and the screen shows a single **Set up this deployment** entry
instead of a sign-in form. Setup runs in one door and closes for good the moment
the owner exists.

![The Studio setup screen asking for the setup token.](https://mintcdn.com/tai42/iRrtHiBZz_SZ94au/images/studio/login-setup-token-light.png?fit=max\&auto=format\&n=iRrtHiBZz_SZ94au\&q=85\&s=1702de7488a955455b3762a408ae3492)

The setup entry at /login on a fresh deployment: enter the setup token from the server log.

The entry asks for the **setup token** first — the value the server prints once
at startup, or the one you pinned with `TAI_SETUP_TOKEN`. A deployment whose humans
sign in through OIDC still needs this token, and the server prints none under several
conditions; [initializing a deployment whose logins are OIDC](/guides/access-control#initializing-a-deployment-whose-logins-are-oidc)
covers why and when. The token unlocks the
owner form in the browser; it reaches the server only with the setup request
itself. A valid token reveals the owner fields. On an accounts-enabled deployment
the form collects a **Display name**, an **Email**, and an **Owner login** choice —
*Set a password now* or *Send me an invite link* — with a **Password** field when
you set one now. On a keys-only deployment the form collects the display name
alone, and the minted key is how the owner signs in:

![The Studio owner-creation form collecting display name, email, the Owner login choice, and a password.](https://mintcdn.com/tai42/iRrtHiBZz_SZ94au/images/studio/login-setup-owner-light.png?fit=max\&auto=format\&n=iRrtHiBZz_SZ94au\&q=85\&s=7b96e4ae50390b6f4edaf6d53b0a1a08)

After a valid token: the owner form. On an accounts-enabled deployment it collects a display name, an email, the Owner login choice, and a password.

Submitting sends one `POST /api/setup`, which creates the owner and mints the
owner's first key. The key is shown **once** — copy it then, it cannot be
retrieved again. When you set a password, the screen confirms it for the owner's
email; **Continue to the Studio** signs you in as the owner:

![The setup success screen showing the owner's key once and the password-set confirmation.](https://mintcdn.com/tai42/iRrtHiBZz_SZ94au/images/studio/login-setup-success-light.png?fit=max\&auto=format\&n=iRrtHiBZz_SZ94au\&q=85\&s=269109defb25b790509917f65c06e091)

Setup complete: the owner's API key shown once, a note that the password is set for the owner's email, then a step into the Studio as the owner.

From then on the screen shows the ordinary sign-in methods, and setup is refused.
On an accounts-enabled deployment this is the password form — email and password
with a **Sign in** button — and the key field collapses behind *Use an API key
instead*:

![The Studio sign-in screen showing the password form with the API-key fallback collapsed.](https://mintcdn.com/tai42/iRrtHiBZz_SZ94au/images/studio/login-signin-light.png?fit=max\&auto=format\&n=iRrtHiBZz_SZ94au\&q=85\&s=2f7e7806ffd6ec2e7ec19ca61f635bcd)

After setup: /login shows the password form, with the API-key field collapsed behind Use an API key instead, and no setup entry.

## Invites

An admin grows the user set from the [Members
page](/studio/admin-console#members). An invited person opens their invite link, which
carries an invite token; the login screen recognises the token and shows a
**set-your-password** form that activates the account. Invites are single-use and
time-bounded — an expired or already-used invite is refused.

## Claim links

A [claim link](/concepts/owned-keys#access-channels) reaches an
[owned key](/concepts/owned-keys) to a new device without the raw secret ever
travelling in a request URL — the `<origin>/login#claim=<token>` **fragment** is
never logged. When the sign-in screen loads with a `#claim=` fragment it exchanges
the token once at the always-public `POST /api/login/claim` and signs the Studio in
with the returned key — the same held-in-the-browser session the key field
produces, with no typing. A spent, unknown, or expired token fails the same
indistinguishable way and the screen falls back to the ordinary sign-in controls;
mint a fresh key and link when one fails.

[Owned keys](/concepts/owned-keys#access-channels) covers the one-time, TTL-bounded
exchange in full. Claim links are created in the [API-keys](/studio/api-keys)
create dialog (or via [`tai keys claim-link`](/reference/cli/keys)).

## API-key fallback

The **API-key** field is always available, behind an *"Use an API key instead"*
toggle when login methods are present. Pasting a deployment key signs the Studio
in exactly as it always has — the key is held in the browser and sent on every
request. This path is permanent: it is how an operator reaches a server that has
no accounts provider, and how the headless, machine-key path stays usable
alongside human login. See [API keys](/studio/api-keys) for provisioning keys.

## Deploy notes

To turn on human login, a deployment enables an accounts provider and lists it
in the auth-provider chain:

* Add the accounts provider's module to the server's lifecycle and router
  modules so its login routes and session validation are mounted.
* Include the provider in `ACCESS_CONTROL_AUTH_PROVIDERS` — the ordered
  [auth-provider](/concepts/access-control) list the gate resolves credentials
  against — so its sessions are validated.
* Run the accounts plugin's migrations. A Postgres-backed provider ships its own
  [migration chain](/concepts/marketplace#the-migrations-contract), applied by the
  framework runner with `tai db migrate` alongside the core; the provider refuses
  to serve until it is applied. See [Accounts](/plugins/tai42/accounts-postgres#run-the-migrations).

> [!NOTE]
>
> The concrete settings, schema, and migration steps for a specific accounts provider
> live in that plugin's own repository README — this page covers the
> skeleton-side wiring that every accounts provider plugs into.

## See also

* [Accounts](/concepts/accounts) — the session, ownership, and role model behind
  sign-in.
* [Access control](/concepts/access-control) — multi-provider resolution and the
  public login namespace.
* [API keys](/studio/api-keys) — the key fallback and owned credentials.


# Author a Studio plugin
Source: https://docs.tai42.ai/studio/plugins

Extend the Studio shell with pages, panels, tabs, nav entries, and route panels.

A Studio plugin extends the browser shell itself — it contributes full pages, rich tool-run panels, settings tabs, sidebar nav entries, and conversation route panels to a running Studio. It is distinct from a server code plugin, which runs in the Python process and adds HTTP surface, while a Studio plugin is a browser ESM bundle that the shell loads at runtime.

A deployment turns a Studio plugin on by naming its **package** in the server [manifest](/concepts/manifest)'s `studio_plugins` list. Each named package ships its plugin dist alongside a `studio-manifest.json`; the skeleton serves the assets under `/api/plugins/{name}/studio/` and injects them into the shell.

## The registration contract

A plugin bundle exports a single `register(context)` entry. The host imports the bundle, calls `register` with a `PluginContext`, and awaits it; every contribution flows through that context — there are no free registration functions.

```ts theme={null}
import type { PluginEntry } from '@tai42/studio-sdk';

export const register: PluginEntry = (context) => {
  context.registerPage({ path: 'reports', title: 'Reports', component: ReportsPage });
  context.registerNavEntry({ path: 'reports', title: 'Reports', icon: ReportsIcon });
  context.registerToolPanel({ toolName: 'run_report', component: ReportPanel });
  context.registerSettingsTab({ id: 'reports', title: 'Reports', component: ReportsSettings });
};
```

The five methods are:

* **`registerPage`** — a full page mounted under `/plugins/{pluginId}/{path}`.
* **`registerToolPanel`** — a rich run panel for a tool by name, replacing the auto-generated form.
* **`registerSettingsTab`** — a tab in the settings area.
* **`registerNavEntry`** — a sidebar link to one of *this plugin's* pages.
* **`registerRoutePanel`** — a panel on the drill-in of every conversation route on one channel.

The context is **sealed** once `register` settles: a registration made afterward (from a deferred timer or a post-resolve microtask) throws instead of silently dropping, and a `register` that throws commits nothing. The host stamps each contribution with the plugin's identity, so a plugin never supplies its own id and two plugins may register the same `path` without colliding.

## Deep-linkable pages

A contributed page is mounted at `/plugins/{pluginId}/{path}`. By default it matches that path exactly and receives only its `pluginId`. To make a page **deep-linkable** — bookmarkable, shareable, back-button-correct — declare a `params` schema (a `PluginPageParamsSchema`) on the `PageContribution`:

```ts theme={null}
context.registerPage({
  path: 'flows',
  title: 'Flows',
  component: FlowsPage,
  params: {
    parseParams: (remainder) => parseFlowsParams(remainder),
    parseSearch: (raw) => parseFlowsSearch(raw),
  },
});
```

When a page declares a schema it becomes addressable under its `path` **as a prefix**. The shell resolves a URL to a page by **longest registered prefix**, then hands the sub-path remainder after that prefix to `parseParams` and the raw search object to `parseSearch`. Each parser **validates and shapes** its input and **raises** on anything it rejects — the shell renders that throw as a loud error card, never a blank or partial view. The validated results arrive on the page as the optional `params` and `search` props of `PluginPageProps`.

Both parsers are optional and independent. Omit the whole schema and the page keeps its exact-path-only behavior and receives neither prop; omit just `parseParams` and the page still matches only its exact `path`; omit just `parseSearch` and `search` is not forwarded. Because every part is additive, deep-linkable pages are a non-breaking addition — the plugin API version does not move.

Navigate between a plugin's own pages with the `usePluginNavigation` hook, whose `navigatePlugin` drives a client-side transition and `resolvePluginPath` yields the href. These target a **runtime plugin path** — `/plugins/{pluginId}/{pagePath}` plus an optional validated sub-path and search — **not** a shell route token: the compile-time `routes.ts` never learns plugin paths, and the token-typed shell navigation (`useAppNavigate`) knows nothing of them. This is how a page derives its whole view state from the URL: it reads `params`/`search` to render, and calls `navigatePlugin` to move, so the browser's history, bookmarks, and back button all work.

## Nav entries

`registerNavEntry` adds a sidebar link, and its `path` must match a page the same plugin also registers — a nav entry with no backing page is a dead link and is **rejected loudly**. The optional `icon` is a component rendering a square inline SVG that fills its box and draws with `currentColor`; the host constrains it to a fixed 1em box, `aria-hidden` (the title is the accessible name). The icon's bytes live inside the bundle, so there is no external fetch and no CSP change. Omit it for a text-only entry, exactly like the core nav.

The optional `section` names the sidebar group the entry renders in — one of the built-in sections (`Capabilities`, `Connections`, `Triggers`, `Activity`, `Administration`). A named built-in section places the entry inside that group, after its core rows; omit it (or name an unrecognised section) and the entry renders in a single shared **Plugins** section placed after the core sections. Every undeclared entry — from every contributing plugin — lands in that one group, each keeping its own title and its own host-applied provenance badge. The field is additive — an older bundle without it simply lands in the shared **Plugins** section, so the plugin API version does not move.

The same set is declared statically in the plugin's `studio-manifest.json` under `contributions.nav_entries`, so the server-side catalog and read surfaces can report a nav-contributing plugin without executing its bundle. That manifest field is the declarative parity of the runtime `registerNavEntry` for the page path only — its schema is a `list[str]` of page paths and cannot carry `section`, which is a runtime-API field alone. It carries the same backing rule: every `nav_entries` entry must appear in the plugin's `pages`, or manifest load fails loudly.

## Route panels

A channel plugin decorates the conversations drill-in of its own channel's routes with `registerRoutePanel`. The slot is keyed by the channel **name** — the route row's `channel` — and the host names no channel: it looks the drilled route up in the route catalogue and renders the panel registered for that row's channel, if any, above the thread list.

```ts theme={null}
export const register: PluginEntry = (context) => {
  const base = context.routeBase('relay'); // this plugin's route item, or null
  setRelayBase(base);
  context.registerRoutePanel({
    channel: 'relay',
    title: 'Relay settings',
    component: RelayPanel, // receives { pluginId, route }
    ...(base === null ? {} : { requiredCapabilities: { routes: [`${base}/settings`] } }),
  });
};
```

* The panel receives `{ pluginId, route }`, where `route` is the `channel`-door row as `GET /api/conversations` lists it.
* One panel per channel deployment-wide: a second registration for the same channel, by this or another plugin, throws and that plugin loads nothing.
* The panel renders inside a region named by its `title`; a panel that throws is contained in an error card labelled with that title, and the rest of the drill-in keeps working.
* `requiredCapabilities` gates it like every other contribution — absent means a full projection only.
* The manifest lists the same channels under `contributions.route_panels`. A bundle whose registered route panels differ from its manifest fails to load loudly.

## Reaching the plugin's own routes

A plugin's route items are mounted under bases a deployment may remap, so a bundle never hard-codes its paths:

* **`context.routeBase(itemName)`** returns the resolved absolute base of one of this plugin's route items (for example `/api/channels/web`), or `null` when the item has no mount on this deployment — an optional router not listed, a channel not loaded. It never throws, so a missing optional router never takes the plugin's other contributions off the Studio. Call it during `register` and keep the value; each feature that needs the base shows its own unavailable state for `null`.
* **`useApi().request(path, schema, options)`** is the host's authenticated request for those routes: the same auth header, error classes and `{ data }` unwrap as every core call. The plugin passes its own zod schema; an answer that misses it throws the api-client's `ApiSchemaError`. A 401 throws the api-client's `ApiUnauthorizedError` — the host's own query cache does not see a plugin's calls, so the plugin routes it to sign-in with the SDK's `useOnUnauthorized()` handler (in its own query cache's `onError`, or where it awaits the call). The api-client's errors are recognised by `error.name`, since a plugin bundle does not import the api-client's classes. Core routes use the client's named methods.

The bases come from the authed plugin listing (`GET /api/plugins`), whose entries carry `mounts`: the plugin's route items and the base each is served under, read off the routes the server is serving now.

## The built-in jq editor

A plugin field that holds a jq expression renders the platform's **built-in visual jq
editor** — no registration, no extension point, no gating. The
[Studio SDK](/reference/studio-sdk/index) re-exports the
[jq-studio](/studio/jq-editor) `JqField` component and its declaration types; the
Studio host injects the design system through a `PrimitivesProvider` and installs the
editor's evaluation worker once, at the shell. A plugin simply imports `JqField` and
renders it — the visual canvas is present by construction, exactly as it is on every
host field and every flow field.

```ts theme={null}
import { JqField } from '@tai42/studio-sdk';
```

A jq field declares what the expression's input document is, seeds a sample for the
editor's Test panel, and optionally supplies a server-validate hook — the declaration
threads onto the field so its context chip, Test seeding, and Validate action read
from one object. See [the jq editor](/studio/jq-editor) for the component and
[jq-studio's repository](https://github.com/tai42ai/jq-studio) for its full API.

A plugin rendering a server schema through `SchemaForm` gets the editor with no code
at all: a string property carrying the
[`x-tai42-expression` annotation](/reference/api/index#expression-fields) renders
`JqField` automatically, with the annotation's own label, blurb, and sample. The
import is lazy, so a form with no annotated field never bundles the editor.

> [!NOTE]
>
> **Migrating from the expression-editor extension point.** SDK 8 removed the optional
> `registerExpressionEditor` context method, the `ExpressionField` and
> `ExpressionEditorsProvider` components, the expression-editor `contributions`, and the
> separate editor-props contract version. A plugin that consumed those symbols now
> imports `JqField` (and its declaration types) from the SDK's jq re-export and renders
> it directly — there is no editor to contribute, resolve, feature-detect, or version.
> The editor is built in, so a jq field is always available; the "no editor registered"
> degradation the old extension point admitted no longer exists.

## The plugin manifest

Every plugin ships a `studio-manifest.json` next to its dist. It is parsed strictly — an unknown field is a loud rejection — and carries:

* **`name`**, **`version`** — the plugin's package identity.
* **`api_version`** — the Studio-plugin API version the bundle targets (see below).
* **`entry`** — the ESM bundle filename the host imports.
* **`integrity`** — a map of every emitted asset filename (the entry bundle and every lazy chunk, plus any stylesheet) to its `sha384-<base64>` subresource-integrity hash. The host serves only integrity-listed files and injects each with its SRI hash.
* **`contributions`** — the declared `tool_panels`, `pages`, `settings_tabs`, `nav_entries`, and `route_panels` (channel names; defaults to none).

## The api\_version gate

The plugin API carries a single monotonic integer, `STUDIO_PLUGIN_API_VERSION` (currently `1`), bumped only on a **breaking** change to the plugin API or to the public prop surface of a design-system component the SDK exports. The host accepts a plugin **iff** the plugin's targeted `api_version` exactly equals the host's; anything else is rejected with a "must be rebuilt" error card, and the plugin commits nothing.

Equality is the correct gate because additive changes never bump the version — a host that gains a new optional capability keeps the same version, so every existing plugin keeps loading. The one asymmetry the equality gate leaves is a plugin that *uses* a newer capability on an *older* host that lacks it; that fails loudly by construction (calling a context method the host does not define throws during `register`, caught as that plugin's error card), never through silent negotiation.

## Styling: two sanctioned paths

A plugin styles itself in exactly one of two sanctioned ways, and no other:

1. **SDK components plus inline styles** that read the design-system tokens (`var(--tai-*)`). Raw Tailwind utilities are host-internal and are not part of this contract.
2. **A plugin-shipped scoped stylesheet**, listed as a `.css` asset in the manifest `integrity` map and host-injected as an SRI'd `<link rel="stylesheet">` before the bundle's JS is imported.

A scoped stylesheet is bound by three hard rules:

* **No global resets or preflight** — never style `html`, `body`, `:root`, `*`, or bare element selectors at the top level.
* **Scope every selector** under a plugin root class the plugin renders itself, prefixed with the plugin's own package name.
* **Theme through the tokens** — colors in plugin-authored rules come from the SDK custom properties (`var(--tai-*)`), never hardcoded, so the stylesheet themes itself with no logic of its own. Bundled third-party base CSS is exempt from this rule, but the no-global and scoping rules still bind it.

> [!NOTE]
>
> Stylesheet injection is a **host capability**. A plugin shipping a `.css` asset to a host that does not inject stylesheets is served but never injected — the page renders with SDK-component styling only. This is the single quiet degradation the mechanism admits, so pair a Studio host with plugins built for it.

## See also

* [The jq editor](/studio/jq-editor) — jq-studio, the built-in visual jq editor a plugin's jq fields render.
* [Plugin API reference](/reference/studio-sdk/plugin-api) — the `PluginContext`, contribution types, the `PluginPageParamsSchema`, and the version gate, generated from the SDK.
* [Navigation reference](/reference/studio-sdk/navigation) — `usePluginNavigation`, `navigatePlugin`, and `resolvePluginPath`.
* [The manifest](/concepts/manifest) — the `studio_plugins` field that turns a plugin on.
* [The screens](/studio/screens) — the shell surfaces a plugin's pages and nav entries join.
* [Studio SDK reference](/reference/studio-sdk/index) — the hooks and shared components a plugin builds from.


# Presets
Source: https://docs.tai42.ai/studio/presets

Author versioned tool presets and bake fixed kwargs, including secret references to environment keys.

The Presets screen manages [presets](/concepts/presets) — named, versioned wraps
of a base tool with baked constants, an optional output schema, and extension
sets. The screen is a master list on the left and a detail-and-editor on the
right, the same shape as the other Capabilities screens.

![The Presets screen listing presets with their base tool, active version, tags, and extension counts.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/presets-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=0d8bbe296996779bcc4f2cc18942816b)

The Presets screen: the list of presets with their base tool, active version, tags, and extension counts.

## The list and detail

**All presets** lists every preset with its name, base tool, description, active
version, tags, and extension count. Selecting a row opens the preset's detail: its
current body — base tool, fixed kwargs, output schema, and extension sets — and its
version history. The detail also edits the preset's
[display name and tags](/concepts/tool-organization); folder navigation and hide
controls live on the Tools screen.

## Create a preset

**Create preset** opens a dialog for a new preset: its **Name**, an optional
**Description**, the **Base tool** it wraps, the **Fixed kwargs** baked into every
run, **Tags**, ordered **Extension sets**, and an optional **Output schema**. The
Base tool must be chosen first — the fixed-kwargs editor suggests that tool's own
input names and the create route rejects a kwarg the base tool does not declare.

## The fixed kwargs editor

**Fixed kwargs** are the constants baked into the preset, applied on every run and
hidden from the tool's caller. The field offers two views behind a **Fields · JSON**
switch: **Fields** edits one typed row per kwarg; **JSON** edits the raw object. The
two stay in sync — switching serializes the rows to JSON or reparses the JSON into
rows — and both are the same `fixed_kwargs` object.

![The create-preset dialog's fixed-kwargs editor in Fields view with a text row, a number row, and a secret-reference row.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/preset-kwargs-fields-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=9f35012158217f7e7cc8191aee8e6d83)

The fixed-kwargs editor in its Fields view: a text row, a number row, and a secret-reference row with its masked, revealable environment-key reference.

Each row has a **Key**, a **Type**, and a value control for that type:

| Type | Value control |
| - | - |
| **Text** | a text input — a plain string constant. |
| **Number** | a numeric input; a value that is not a finite number blocks saving. |
| **Boolean** | a `true` / `false` select. |
| **Null** | no value — the kwarg is `null`. |
| **Secret reference** | an environment-key picker (see below). |
| **JSON** | a read-only preview of a nested object or array, with **Edit as JSON** to switch to the JSON view. |

**Add kwarg** appends a blank row; each row has a **Remove** button. The base tool's
input names are offered as suggestions on the Key input.

### Secret references

A **Secret reference** row bakes a pointer to an environment value instead of the
value itself. It stores **only the environment variable's name**; the server reads
the value from its environment when the preset binds, and masks it wherever a run is
recorded. You cannot paste a value here — the row picks from the keys already added
on the [System › Environment](/studio/admin-console#settings-and-environment) tab,
so the credential is never typed into the preset:

> Add the secret on System › Environment, then reference it here.

A reference may carry an optional **Default (stored in the clear)**, used when the
variable is unset. The default is ordinary non-secret config — it is stored,
versioned, and exported in the clear — so never write a credential as a default. It
cannot contain `{` or `}`, which would break out of the `${VAR:default}` marker.

Under the field, the editor states the rule plainly: *A secret reference stores only
the environment variable's name; the server reads the value when the preset binds. A
default is stored in the clear, so never write a credential as a default.*

If the environment keys cannot be listed, the row degrades to a plain **Environment
variable** input — you type the name — with the hint *Environment keys could not be
listed; type the variable name.*

### The JSON view

The **JSON** view shows the same kwargs as raw JSON, and is where a nested object or
array is edited. A reference is the exact marker the server resolves at bind time —
`!ENV ${VAR}`, or `!ENV ${VAR:default}` with a default:

![The fixed-kwargs editor in JSON view showing a secret reference as an !ENV marker.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/preset-kwargs-json-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=8a60bb8c6fa40e45fbbc46852ae5787a)

The same kwargs in the JSON view: the secret reference is the literal !ENV marker the server resolves at bind time.

### Validation

A row is flagged inline when its key is blank (**Key is required**), duplicates
another row's key (**Duplicate key**), is a number that does not parse (**Not a
number**), is a reference naming no variable (**Environment variable is
required**), or is a reference whose default contains `{` or `}` (**Default must not
contain&#x20;**). While any row is invalid the field shows **Fix the highlighted kwarg
before saving.** and **Create**, **Validate**, and **Save as new version** are
disabled, so a half-edited kwarg can never be written. Malformed raw JSON forces the
JSON view and reports the parser's message; the Fields switch stays disabled until it
parses.

## Save a version and roll back

Editing a preset's body and saving mints a **new version** — presets are immutable
per version, and the same fixed-kwargs editor and validation gate the save-version
dialog. The version history lists every version; **rollback** makes an earlier
version active again without losing the later ones.

The same operations are available from the CLI (`tai presets list`,
`tai presets versions <name>`, `tai presets rollback <name> <version>`). See
[Presets](/concepts/presets) for the full model and
[Configuration and secrets](/concepts/config-and-secrets) for how environment
references are resolved.


# Running tools
Source: https://docs.tai42.ai/studio/running-tools

Synchronous runs versus detached background runs, and the trade-off between them.

The Tools screen offers two ways to run a tool, with a deliberate trade-off. A
synchronous **Run** is simple and immediate; a **Run in background** survives a
dropped connection. Pick by how long the tool takes and whether the result must
outlive the browser tab.

![A tool run panel showing a synchronous result.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/tool-run-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=6717af60d3e8b10a8c3577eba964da88)

The run panel: a synchronous result, with Run and Run in background above it.

## Run (synchronous)

**Run** issues a single `POST /api/run-tool` held open until the tool finishes,
then renders the typed result inline. It is the right choice for a fast tool
whose result you want immediately.

The catch is that the result lives only on that one open connection. If the
browser closes, a proxy times out, or the client-side timeout fires, the result
is gone — even though the tool may still be executing server-side, side effects
and all.

> [!WARNING]
>
> The panel marks a client-side timeout as a distinct **still executing
> server-side** state, never a generic failure. Do not retry: the original run's
> side effects may still be completing.

## Run in background

**Run in background** issues `POST /api/tool-runs`, which returns a `run_id`
immediately and runs the tool as a detached task. The Studio then polls for the
outcome and keeps a per-tool **Recent background runs** list. Use this for long
or interactive [human-in-the-loop](/concepts/interactions) tools.

**1. Start the run**

`POST /api/tool-runs` returns a `run_id` and the skeleton runs the tool
detached.

**2. Poll for the result**

The Studio polls `GET /api/tool-runs/{run_id}` every two seconds, stopping on
a terminal state.

**3. Read the outcome**

The result is retrievable from the record until it expires — the skeleton's
`TAI_TOOL_RUNS_RESULT_TTL_SECONDS`, 24 hours by default.

A background run reaches one of four states:

| State | Meaning |
| - | - |
| `running` | The tool is still executing. |
| `succeeded` | The tool returned; its result is on the record. |
| `failed` | The tool raised; its error string is on the record. A run that reached a failed terminal (a flow or an agent run) records `tool run failed` and the run's outcome whole under `outcome`; the Studio shows it in an **Outcome** section. |
| `lost` | The skeleton restarted mid-run — the result is unrecoverable. |

> [!NOTE]
>
> **`lost`** means the skeleton restarted while the run was executing. The Studio
> says so plainly rather than pretending the run failed or never happened.

## What background runs are not

* **Not streaming.** Progress is observed by polling, not a live feed — there is
  no partial-output stream for a tool run.
* **TTL-bounded.** Run records live in the skeleton's Redis with a TTL; there is
  no permanent run history, and an expired `run_id` is a plain `404`.
* **Not durable across a restart mid-run.** An in-flight run whose process dies
  becomes `lost`. Background execution buys disconnect-survival for the *client*,
  not crash-recovery of the run itself.

> [!NOTE]
>
> Background runs require the skeleton's Redis-backed run store. A server without
> it still runs tools synchronously; the **Recent background runs** list reports
> the store as unavailable rather than faking a history.

> [!NOTE]
>
> The list is not limited to the **Run in background** button. When the run store is
> configured, a tool fired by a [hook, webhook, or trigger link](/concepts/hooks) is
> recorded in the same store — under the firing execution key — and surfaces in that
> tool's **Recent background runs**, gettable by run id like any background run.

See the [HTTP API reference](/reference/api/index) for the run and tool-run
routes, and [live operations](/concepts/live-operations) for reloading tools on
a running server.


# The screens
Source: https://docs.tai42.ai/studio/screens

A tour of every surface in the Studio sidebar.

The Studio's left sidebar leads with the **Dashboard** row, then groups every
feature into five intent sections:

* **Capabilities** — Tools, Agents, Presets, States, Extensions, Templates.
* **Connections** — Connectors, Served endpoints.
* **Triggers** — Hooks, Scheduling.
* **Activity** — Conversations, Interactions, Notifications.
* **Administration** — Settings, Storage, Marketplace, Manifest, System.

Each screen drives one slice of the server's `/api/*` surface, and every screen
renders its own loading, empty, and error states rather than a blank page. This
page tours the surfaces you reach most. A [Studio plugin](/studio/plugins) adds
its own links to one of these sections, or to a single shared **Plugins** section
that follows them.

## Tools

The Tools screen lists every [tool](/concepts/tools-and-extensions) the
[manifest](/concepts/manifest) loaded — your own functions, mounted MCP servers,
the standard toolbox, and any [extension](/concepts/tools-and-extensions)
variants (a `_batch` or `_chain` branch appears as its own runnable tool).
Select one to open its run panel.

![The Tools screen with a list of loaded tools.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/tools-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=0bee7e0b59692ae790dfb52b2f0c39ec)

The Tools screen: the master list of loaded tools and the run panel.

Running a tool has two modes — a synchronous run and a detached background run.
[Running tools](/studio/running-tools) covers the trade-off in full.

The Tools screen is also where you organize the namespace through the
[tool-organization overlay](/concepts/tool-organization). The list is a
current-directory explorer: a breadcrumb, the current folder's subfolders, then
the tools filed there, with unfiled tools at the root. Each tool renders its
display name (its real name stays visible beside it) and groups by its **merged
tags** — the tool's read-only plugin-native tags unioned with your editable user
tags. A tool whose effective visibility is hidden is excluded from this list
outright — there is no toggle to reveal it; hiding is a display convenience, never
a security boundary — a hidden tool stays callable. To bring one back, set its
visibility to **Shown** from the CLI or API (`tai tool-meta set <tool> --visibility
shown`); once shown it appears here again. The per-tool **edit dialog** is the one
surface that edits all four overlay fields: display name, user tags, folder, and a
three-way visibility control (**Default** defers to the plugin's declaration,
**Shown** forces it visible, **Hidden** forces it out of the lists).

Each folder row carries **Rename** and **Move** actions; Move offers the folder
tree as a parent picker (with inline create) and excludes the folder and its own
descendants, so a folder can never become its own ancestor. Both appear only for a
session that can write the overlay.

The screen also carries the app-tool live-registry admin card — **Reload** re-registers
one app tool and **Remove** detaches it from the running registry, each named by its
reloader `kind` and `name` and applied across the fleet. Reload is non-destructive;
Remove asks the house confirm first. The card renders only for a session whose
projection reaches those fenced doors.

## Agents

The Agents screen lists the [agents](/concepts/agents) the manifest registered,
each with a **Run** entry that opens its run panel. **Compose agent** authors a
new agent as a saved spec — a prompt, a tool selection, and presets baked over a
base agent — that versions and rolls back like a [preset](/concepts/presets); the
authored-agents panel is empty until you compose one.

![The Agents screen with an empty authored-agents panel above a manifest-registered tools\_agent carrying a Run control.](https://mintcdn.com/tai42/v1yzjdfTNmibN0er/images/studio/agents-light.png?fit=max\&auto=format\&n=v1yzjdfTNmibN0er\&q=85\&s=f3dc413f756f3f2df8f50a04971f2f3c)

The Agents screen: the authored-agents panel above the manifest-registered agents, each with a run entry.

## Extensions

The Extensions screen is where you attach a clip-on power — a chain, batch, or
monitor [extension](/concepts/tools-and-extensions) — to a tool, and browse the
extension catalog of variants already registered. Pick a tool in the apply form
to view and edit its combos; each catalog entry lists its variants and their
transform.

![The Tool extensions screen with a tool picker for applying an extension above a catalog listing the ask variant.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/extensions-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=9bfc70b79deb33073ced17e0171e1031)

The Tool extensions screen: the apply-an-extension form above the extension catalog of registered variants.

## Templates

The Templates screen browses the stored resources the
[ResourceManager](/concepts/storage-and-resources) serves — jinja templates and
other content held in the configured storage backend. Select one to view and
render it. The upload form writes new resources two ways: a **Text** mode types a
single template inline, and a **Files** mode picks many files at once — each file
becomes a template keyed by its name. A files upload checks every path for a
conflict up front and blocks the whole batch before writing if any name already
exists or repeats, so a bulk upload never half-overwrites the store. Each folder
row carries a delete affordance — a destructive confirm that removes every template
filed under that prefix — and a selected template's detail deletes it behind its own
confirm.

![The Templates screen listing stored template resources.](https://mintcdn.com/tai42/bINQCOa9tAPaBpjw/images/studio/templates-light.png?fit=max\&auto=format\&n=bINQCOa9tAPaBpjw\&q=85\&s=6f51caecab38ec1df4083ba7453278f6)

The Templates screen: stored resources with a viewer and an upload form.

> [!NOTE]
>
> The Templates screen is populated only when the server has a storage backend
> registered. A server with no backend reports the surface as unavailable rather
> than inventing an empty list.

## States

The States screen drives the platform [state store](/concepts/states) — the
declared documents every door reads and writes per subject. It lists each declared
state with its subject kinds, record and consumer counts, and last update, above a
**Declare state** action and an **Upload** action that routes a `.json` file to the
state or state-template upload door by its `kind`.

![The States screen listing declared states with subject-kind badges and record and consumer counts.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/states-list-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=6e1e817ac9058020bc8d0db86ea13c52)

The States screen: declared states with their subject kinds, record and consumer counts.

A **Pending saves** card sits above the list whenever the store is on: the
[pending saves](/concepts/states#pending-saves) not yet applied, refreshed every ten seconds,
with a summary of how many are outstanding and how many failed. It opens on the **Failed** tab
(or **All outstanding** when nothing has failed) and pages with **Load more**. Each row shows the
save's status badge (Pending, Calls queued, Calling, or Failed), its first subject and how many
more, the calls it runs, its run, age, attempts, and last error. A failed row offers **Retry**,
which reports whether the save applied, was queued again, or failed again, and **Discard**,
behind a confirm that warns its writes and calls will never be applied.

![The Pending saves card listing a failed save with its validation error, Retry and Discard actions, below the newer pending save on the same subject.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/states-pending-saves-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=4e740c98f57ec6d6c515e0200feeba2e)

The Pending saves card on its All outstanding tab: a failed save with Retry and Discard, and the newer save on the same subject waiting behind it.

Opening a state leads to a detail page with four tabs. The **Declaration** tab edits
the base JSON Schema as a nested field tree — attached subtrees are read-only and
badged with their template — or points it at a stored template whose rendered value
is the schema, with the resolved schema shown beneath; both sit beside the subject
section (the kinds and the default kind; `person` keys are person ids from the
conversations identity store) and the retention setting. Once a state has records the editor accepts only additive
changes: removing or changing an existing field is refused.

![The Declaration tab editing a state's base schema as a field tree with the subject kinds and retention settings.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/states-declaration-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=5a3e730a77363a96e1cca8edd09a704f)

The Declaration tab: the base schema as a field tree beside the subject and retention settings.

The **Templates** tab lists the state's attachments — template, path, and the
parameter and declaration counts — with **Edit declarations** and **Detach** actions and
an **Attach template** form that renders the template's parameter and declaration schemas
as fields. Below the attachments, a **State templates** section lists the platform
state-template documents, each with its attached-on count and a **shipped default** badge,
and an **Upload template** action; deleting a template that is still attached is refused.

![The Templates tab listing one attachment with its template, path, parameter and declaration counts and the edit and detach actions, above the State templates section with its Upload template action.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/states-templates-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=e7e668ea29b050cab0812e585f88a7ef)

The Templates tab: the state's attachments above the platform state templates.

The **Records** tab looks up one subject — a kind, a key, and a conversation target —
lists a state's subjects with a keyed **Load more**, and searches records by document
content. A found record opens the record page. When some of the listed subjects are held by a
failed pending save, a line above the table counts them, says their rows show the last applied
data, and links to the Pending saves card.

![The Records tab's Subjects table of thread subjects t-001 and t-002, below a line saying one subject on this state is held by a failed pending save and shows its last applied data, with a link to Pending saves.](https://mintcdn.com/tai42/mNH8SxuFXcGoykam/images/studio/states-records-held-light.png?fit=max\&auto=format\&n=mNH8SxuFXcGoykam\&q=85\&s=d2af6a631484637aeaf58d46ae5166f2)

The Records tab's subjects with the line that counts the subjects a failed pending save holds.

![The Records tab with a subject lookup form above a list of the state's subjects.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/states-records-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=5fd5387966b14c614701030126b5a503)

The Records tab: the subject lookup form above the state's subjects.

Below the subjects, a **Check records against the schema** card runs the
[stored-records check](/concepts/states#checking-records) against the state's current
effective schema. A **Kind** select narrows it to one subject kind, and **Check
records** walks every page of the state's records and reports a summary — *N checked —
M do not fit* — above a table of the misfits only: each row carries the subject, its
target, when it was last updated, and its reasons as `path — message`, and links to the
record. A state whose records all fit shows the count with no table; a store that is off
reports the surface as unavailable rather than an empty result, and a page that fails
part-way through the walk surfaces the error with a retry rather than a partial summary.
A line above the table names any subjects a failed pending save made the check skip.

![The Check records against the schema card: a Kind select set to thread and a Check records button above the summary 2 checked — 1 do not fit, and a table with one misfit subject t-001 for tool studio\_demo\_echo, its last update, and the reason \$.items\[0\].id — 7 is not of type 'string'.](https://mintcdn.com/tai42/jD9sf4htAEuXkH0Z/images/studio/states-records-check-light.png?fit=max\&auto=format\&n=jD9sf4htAEuXkH0Z\&q=85\&s=d8f46859b2c16adde56cc369d8503d1b)

The Check records card after a check: the count of records checked and the misfits, each with its target, last update, and reasons.

The **Consumers** tab is the union of everything that binds the state — flows, hooks,
schedules, and agents — each with an **Open** link to the surface that owns it. A
consumer family the deployment cannot serve (no scheduling backend, for instance) is
shown as a muted line rather than swallowed.

![The Consumers tab listing the flows, hooks, schedules, and agents that bind the state.](https://mintcdn.com/tai42/KvPXlWX1hf_jvQ8U/images/studio/states-consumers-light.png?fit=max\&auto=format\&n=KvPXlWX1hf_jvQ8U\&q=85\&s=0782812173fb698478e1384645c6ede4)

The Consumers tab: everything that binds the state, each with an open link.

The **record page** shows one subject's document with an editor over the effective
schema (or a validated JSON textarea when the schema cannot be rendered as a form), a
**Fold into** card that folds this subject into another behind a destructive confirm,
and the **Writes** audit table — each write's time, door, actor, consumer and node,
run id, and the paths it touched.

![The record page showing a subject's document, a fold-into card, and the writes audit table.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/states-record-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=3727fc3bf26945852557b42ba62114bb)

The record page: the subject's document beside its fold action and its writes audit table.

> [!NOTE]
>
> Every States tab reports its own loading, empty, and error state, and the whole
> screen reports the store as unavailable when its database is unbound rather than
> inventing an empty list.

## Dashboard

The Dashboard reads the server's [monitoring](/concepts/live-operations) backend
— run counts, cost, latency, and token totals over a time range, with a
per-model breakdown and a trend chart. The demo instance below is populated from
a monitoring backend seeded with example runs; with no backend registered, it
renders a clean empty state instead. The per-model breakdown shows a distinct
"unavailable for this range" notice when its figures could not be computed, so an
unavailable breakdown never reads as an idle one.

![The observability Dashboard with summary tiles and a trend chart.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/dashboard-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=4197ce90969ac8f9f4fbc31094ad73fc)

The observability Dashboard: run, cost, latency, and token summaries.

## Conversations

The Conversations screen, under **Activity** in the sidebar, is the operator's window
over the [conversation bridge](/concepts/client-conversations) — every route, whichever
door it listens on, in one place. It both **manages** routes and **monitors** their
traffic, and drills down in three levels, each of them a URL you can share or bookmark:
the route picker, that route's threads, and one thread's transcript.

The landing carries three tabs — **Routes**, **Per-target configs**, and **Failed
deliveries** — so only the open one reads its door; on a no-backend deployment each
reports its own off state rather than three stacked empties.

The **Routes** tab is the route picker: it lists every route with the door it answers
(a channel's registry name, or the authed API), the identity that medium reaches you
at, and the agent or tool a turn runs. **Create route** opens an upsert dialog, and
each row edits or deletes its route. The dialog authors the route through a schema
form whose fields follow the target and door — each door shows only its own delivery
fields — and whose rules come from the contract's published route document: a route
name of lowercase letters, digits and hyphens, an optional absolute `https` callback URL
with no user name or password (leave it blank for a poll-only route), a `:`-free channel
name, and an error reply of up to 2,000 characters. A value that breaks its rule is
refused in the form with that field's own message, before anything is sent. Either target kind carries the route's jq programs — `start_expr`,
`reply_expr`, and the door-contract `cancel_expr` / `resume_expr` / `extras_expr` —
each rendering the [visual jq editor](/studio/jq-editor) in place. An
`api`-door save that sets a `callback_url` mints a fresh `callback_secret` and **reveals
it exactly once** in the dialog under a loud caption — every such save rotates it and no
door can re-read it, so copy it then; a `channel` save and a poll-only `api` save (no
`callback_url`) carry no secret and close straight away.

Selecting a route opens its **threads** — one row per client address, with when it
last spoke, how many exchanges it holds, and where its newest answer's delivery stands.
Selecting a thread opens its transcript beside the list; below a 1024px viewport the
split collapses to whichever pane the selection names, with a Back link.

![The Conversations screen with a route's thread list beside a selected thread's transcript.](https://mintcdn.com/tai42/iRrtHiBZz_SZ94au/images/studio/conversations-light.png?fit=max\&auto=format\&n=iRrtHiBZz_SZ94au\&q=85\&s=ddc315fdfd7e012cf9b0908975216c8d)

The Conversations screen: the thread list for a route beside the selected thread's transcript.

The thread list also lets an operator **reset many threads at once**. Each row carries
a checkbox, and a header checkbox ticks or clears every currently loaded row (and shows
a mixed state when only some are ticked). The selection is always the rows on screen —
"select all" means the loaded page, never an unbounded server-side set. A
**Reset selected (N)** danger action, offered only to a session that may delete on the
route, forgets every ticked thread behind the house confirm, whose copy and confirm
label both name the count and state that each thread's transcript and the agent's memory
of the conversation are forgotten and that it cannot be undone. The reset fans the
same per-thread [delete door](/reference/conversation-bridge#forgetting-a-thread) out one
thread at a time — there is no "reset everything matching a filter" server action.
Results are reported **per item**: threads that reset cleanly drop from the list, while a
thread whose reset failed — for example a `409` because a turn is in flight — stays as a
failed row carrying its reason and a **Retry**, so a partial failure is visible and
recoverable thread by thread.

![A route's thread list with every row and the header checkbox ticked under a Reset selected (3) danger button, each row showing its address, last activity, message count, and delivery status.](https://mintcdn.com/tai42/jD9sf4htAEuXkH0Z/images/studio/conversation-bulk-reset-select-light.png?fit=max\&auto=format\&n=jD9sf4htAEuXkH0Z\&q=85\&s=660d42d03f386f1ee97eb8cc0f550787)

Bulk reset: the header checkbox ticks every loaded thread and the Reset selected action names the count.

![The Reset selected threads dialog asking to reset 3 selected threads, saying each thread's transcript and the agent's memory of the conversation are forgotten and that it cannot be undone, with Cancel and Reset 3 threads buttons.](https://mintcdn.com/tai42/jD9sf4htAEuXkH0Z/images/studio/conversation-bulk-reset-confirm-light.png?fit=max\&auto=format\&n=jD9sf4htAEuXkH0Z\&q=85\&s=8dd78e350c0b7d3df9f174e462932cfc)

The bulk-reset confirm: its copy and its confirm label both name the count and say it cannot be undone.

![The thread list after a bulk reset: a summary reading 2 threads reset, 1 thread could not be reset, the failed thread's reason that a turn is in flight beside a Retry button, and the one remaining failed thread still selected.](https://mintcdn.com/tai42/sBSjMnq3V3fvqaIU/images/studio/conversation-bulk-reset-result-light.png?fit=max\&auto=format\&n=sBSjMnq3V3fvqaIU\&q=85\&s=76baeae07809f0c0ee8fbfd195b9c04b)

The per-item result: threads that reset drop from the list, and a thread that failed stays with its reason and a Retry.

A transcript **live-tails**: it re-reads the newest page every few seconds, so a new
exchange lands with no interaction, and the foot of the pane says so. **Load older
messages** pages backwards through history; past a few pages of history the tail
pauses — it says it has, and **Jump to latest** puts it back on the newest page and
resumes it. The thread list refreshes on its own cadence and pauses the same way
when paged deep, with **Back to the newest** to resume.

Each exchange renders the visitor's message verbatim as plain text, the agent's
answer as markdown, and two chips: the answer's outcome and its delivery state.
When the visitor's message carried inbound attachments, they render in the visitor
bubble beside the text — an image inline, a document as a labelled download card,
and audio or video in a native player — each loaded from the platform's own
served-media reference. A `failed` delivery takes the danger tint plus a rule down
the exchange, so a failure never reads as an ordinary row. An admin also gets a **Delivery detail** disclosure
carrying the attempt count, each part sent with its length and provider message ids, and
the retained error.
A message an operator sent [by
hand](/reference/conversation-bridge#operator-messages-and-control-mode) (its record's
`origin` is `operator`) has no visitor side: it shows as one bubble on the agent's
side, labelled **Operator** and set apart by an accent border, so a human's reply reads
as distinct from the flow's.

A message the platform sent on its own (a [send
record](/reference/conversation-bridge#send-records)) is a bubble on the agent's side,
labelled by what the record proves. A send made inside a turn to its participant is drawn
inside that turn's exchange, labelled **Agent**, or **Agent · question** for a question.
Any other send is its own exchange, in neutral colours with a dashed border, labelled
**Sent message**, **Question**, **Platform notice** or **Channel notice**. A question's reply
over the channel shows under it as **Visitor · reply**; for a question asked as sensitive it
reads "Reply received · not stored (sensitive)". A send whose outcome is unknown takes the
danger tint and the rule down the exchange, like a failed one, with the chip **Sent, outcome
unknown**.

A message that replied to an earlier one shows a quote block above it, a muted
inset with a leading rule: **Replying to** and the quoted text in full. When the thread's
record does not hold the quoted message it reads "Replying to a message this thread's record
does not hold. It may be in an earlier thread of this conversation, whose text is not shown
here, or it expired, was forgotten or was never recorded." with the message id; a quote of
an answer to a sensitive question reads "Replying to an answer to a sensitive question. Its
text is not kept."; a quoted message with no text reads "Replying to a message with no
text." A reply to a question shows the same block on its **Visitor · reply** bubble.

![A conversation transcript with a visitor's inbound image and document attachments in the visitor bubble.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/conversation-inbound-attachments-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=96230184548eaf100e12849ea2ec8d74)

A thread transcript with the visitor's inbound attachments — an inline image and a document download card — rendered in the visitor bubble.

![A conversation transcript showing an agent message sent mid-turn inside the visitor's exchange; a Sent message bubble whose open Delivery detail lists part 1 with its length and provider message id; a Question bubble with a reply received but not stored as sensitive; a Platform notice; a failed Channel notice; and a Sent message with the chip Sent, outcome unknown, whose open Delivery detail shows one attempt and the error that the send did not answer in time and its outcome is unknown.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/conversation-transcript-sends-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=cbbbc095c1f06f08fb6e39dfda95189d)

A thread transcript with send records: a send made during a turn inside that turn's exchange, a sent message and a sensitive question asked outside any turn, a platform notice, a channel notice whose send failed, and a sent message whose outcome is unknown, both open on their delivery detail.

![A conversation transcript where one visitor bubble carries a Replying to block with the assistant's earlier answer, and another carries the line saying this thread's record does not hold the quoted message, with its message id.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/conversation-inbound-reply-to-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=cafb726a80ac3404858940be9497e3f6)

A thread transcript with two replies to earlier messages: one quoting the assistant's earlier answer, shown in full, and one quoting a message this thread's record does not hold.

Beside the transcript, an open thread carries two operator actions over the otherwise
read-only monitor:

* A **control-mode** toggle — *Agent replies automatically* — reads the thread's
  [mode](/reference/conversation-bridge#control-mode) and flips it between `agent` (the
  flow answers new messages) and `manual` (new messages wait for a human).
* A **compose box** at the foot sends a reply into the thread by hand, delivered from
  the route identity; on success the tail shows it at once.

Both are the door's **write** action. A capability-scoped or read-only session may set
neither: the refusal is shown inline, never swallowed.

An open thread also carries two destructive actions, each behind the house confirm:

* **Delete thread** forgets this one thread — its transcript records and the agent's
  checkpoint memory of it — so a later message on the same address starts fresh.
* **Erase person** is the GDPR right-to-erasure action, offered only when the thread's
  transcript names a linked person. It erases the person entirely — their aggregated
  thread and checkpoint, their person row, and every address-to-person link — across
  every route they ever wrote under. The confirm states that blast radius plainly. A
  thread whose transcript reads as not found (every record pruned) names no person, so
  the action is not offered there; erasure stays reachable through
  `DELETE /api/conversations/persons/{person_id}` and the CLI.

A route's drill-in also shows the panel its channel's Studio plugin contributes, when
one does — for a web route, the web channel's panel, where the deployment lists
`tai42_channel_web` under `studio_plugins`. It has two sections. The
[**Entry gate**](/plugins/tai42/channel-web#entry-gate) carries the **Require an entry code**
toggle and the route's live codes, each with its label, creation time, expiry, and a
**Revoke** action. [**Words**](/plugins/tai42/channel-web#words) carries one input per word the
route can set: the refusal pages' headings and texts, and the sentences the chat draws when one
of its requests is refused.

![The Entry gate panel with Require an entry code checked and one code labelled launch that never expires, with a Revoke action.](https://mintcdn.com/tai42/RYJVPONTfbkbfgus/images/studio/entry-gate-light.png?fit=max\&auto=format\&n=RYJVPONTfbkbfgus\&q=85\&s=ea726653298b76e5ed9adbc134fea1d8)

A gated web route's drill-in: the Web chat panel's Entry gate section with one live code, and its Words section below it.

A route with no live code says so in the panel.

![The Entry gate panel with its toggle off and a No entry codes notice.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/entry-gate-empty-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=11b702cbbb06c4176be5022800ccb072)

An ungated web route's drill-in: the Web chat panel's Entry gate section with no entry codes.

**Mint entry code** opens a dialog that shows the new code and its chat link — the
route's chat URL with `?tai_entry=<code>` appended — each with a copy control. The
code is shown once: only its hash is stored, so a lost code is revoked and a new one
minted.

![The Mint entry code dialog showing the new code and the chat link with copy controls, a never-expires note, and a Done button.](https://mintcdn.com/tai42/RYJVPONTfbkbfgus/images/studio/entry-gate-mint-light.png?fit=max\&auto=format\&n=RYJVPONTfbkbfgus\&q=85\&s=f192822eabee02e074ff67cbbdc4e42b)

The mint dialog: the shown-once entry code and the chat link that carries it.

**Words** draws the route's set words in their inputs and leaves the rest blank; a blank
input draws the built-in English. A save replaces the route's whole set, and a clear removes
it.

![The Words section listing the refusal pages' heading and text inputs, with Entry refused set to Members only and Ask for a fresh link to join.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/web-words-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=d2989c9d7a731d9a7b663c5465fd2777)

The Web chat panel's Words section, with the entry-refused page's own heading and text set.

When the web channel's routes are not mounted on the deployment, both sections say so —
**Entry gate unavailable** and **Words unavailable** — and nothing can be read or changed
here until the web channel is loaded.

![The Entry gate panel reading Entry gate unavailable, explaining that the web channel's routes are not mounted on this deployment.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/entry-gate-unavailable-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=31640a98892767afbb88f4179747ea63)

The Web chat panel on a deployment where the web channel's routes are not mounted.

The **Per-target configs** tab is the per-target admin surface: each row is a stored
config for one target (its kind and name), whether the target opts into person linking,
and its first-contact greeting. **Create config** opens an upsert dialog; each row edits
or deletes its config behind a confirm. The greeting is a `str.format` template — plain
text, not jq — and may reference at most the `{pairing_code}` placeholder minted at
greeting time; a blank template means no greeting.

The **Failed deliveries** tab lists every answer whose delivery ended `failed`, across
every route and caller, each rendered with the route and address it belongs to and an
admin-only error disclosure. It is an **admin-only** door — a scoped session's refusal
reads as a capability boundary — and it refreshes on its own so a delivery a retry has
since cleared drops off.

> [!NOTE]
>
> A thread listing spans every caller on a route, so its door is **admin-only** — a
> capability-scoped session is told that as a capability boundary, not a failure. The
> screen needs the conversations Redis backend; with none configured, every door
> refuses `501`. See the [read doors](/reference/conversation-bridge#the-read-doors).

## Marketplace

The Marketplace screen browses the [marketplace](/marketplace/index) plugin
index through the server. A Browse tab runs an item-level search with facet
chips for kind, category, and tags and a sort control; an Installed tab lists
the plugins this server has installed and their update availability.

Selecting a listing opens its detail — the items it carries, its version
history, its description, and homepage and repository links; when the plugin is
installed, any security advisories affecting the installed version show there
too. The detail drives [install, update, and
uninstall](/marketplace/install) against the server's `/api/marketplace/*`
routes, with progress surfaced in place.

## System

The System screen is the operational read-out: a health badge from the server's
liveness probe. It is the fastest way to confirm a server is up and answering.

![The System screen showing a 'Healthy' badge from the server's liveness probe.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/system-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=a5ea4fe052af61a906dbce8c3daf1fce)

The System screen: a populated 'Healthy' badge from the server's liveness probe.

> [!NOTE]
>
> The health badge reads `Healthy` on this demo instance, confirming the server is
> up and answering its liveness probe.

## Connectors

The Connectors screen, under **Connections**, is the unified surface for outside
apps and mounted MCP servers. Two provider sections list the
[OAuth providers](/concepts/connectors) you can connect to (grouped by category,
each showing its connection state) and your existing connections; selecting a
connection opens its routed detail, and a popup-blocked sign-in that redirected the
whole tab completes its exchange back here.

The same page is the **two ways to add MCP**. Its MCP section carries both:

* **Status** — every mounted MCP server, healthy or failed, each with a **Reload**
  control. A failed server can be reloaded, or deregistered, in place.
* **Config** — an editor for the manifest's `mcp` array with a form view (one editor
  per entry: a schema-driven transport form plus a tool composer for the
  `include`/`exclude` lists) and a raw-JSON escape hatch over the same working list.
  A connector-owned entry renders read-only — it is kept in sync by its connection, so
  you remove it by disconnecting. Saves cross the config pipeline and reload the fleet;
  a malformed edit is a loud inline error and no request is sent.

> [!NOTE]
>
> The MCP configuration editor and the environment editor under **Settings** each carry
> an unsaved-changes guard: navigating away or a full-page unload with edits in flight
> first confirms, so a half-finished edit that would reload the fleet is never dropped
> silently.

## Served endpoints

The Served endpoints screen, under **Connections**, manages the derived sub-MCP
servers — the [private tool sets](/concepts/private-tool-sets) that serve a curated
subset of tools under their own slug and MCP endpoint. It lists every entry with its
transport and its concrete `/app/{slug}` connect URL (copy-to-clipboard) and a
delete control behind a confirm. **Create** builds a new entry from a slug, a
multi-select of tool names, and a transport; a slug that already exists is flagged and
the replacement confirmed, because register is a silent-swap upsert.

## Manifest

The Manifest screen, under **Administration**, is the config-artifact inspector: it
renders the live [manifest](/concepts/manifest) the server loaded — its `mcp` and
`user_tools` — as an expandable tree. The document is read-only here; it is edited on
disk and reloaded, never mutated from the screen. (MCP server status and config live
on the [Connectors](#connectors) page, and the derived sub-MCP servers on
[Served endpoints](#served-endpoints).)

Below the tree, the screen carries the granular section-editing doors: the `tools` and
`agents` per-entry add and remove controls (an entry is added by pasting its JSON with
its title validated, removed by naming its title), and the `api_tools`
include/exclude curation (a name is added to or removed from a list). These are a
deliberate delta surface — the manifest read serves only `mcp` and `user_tools`. Every
write crosses the config pipeline and reloads the fleet, so a save re-reads the
artifact and reports any failed propagation; removes ask the house confirm. Each door
renders only for a session whose projection can reach it.

![The Manifest screen showing the live manifest config artifact as an expandable JSON tree.](https://mintcdn.com/tai42/_DxZvHo1FLE_bw17/images/studio/manifest-light.png?fit=max\&auto=format\&n=_DxZvHo1FLE_bw17\&q=85\&s=dd9e15c59c49c973cac0c6ac0de1dcaf)

The Manifest screen: the live manifest config artifact as an expandable tree.

## Flows

When the [Babelfish Flows](/babelfish) plugin is installed, it contributes a
top-level **Babelfish Flows** page and its own sidebar entry (and a companion
**Babelfish State** page for the flow engine's declared state). A plugin entry that
names one of the built-in sections joins that group after its core rows; an entry that
names none renders in the single shared **Plugins** section that follows the core
sections, each such entry carrying its own host-applied provenance badge. The Babelfish
Flows page is the flow engine's own editor — its flow canvas, the node edit panels, the
Router card and its dispatch modes, the visual jq editor, and per-node state bindings — documented on the
[Flows editor](/babelfish/studio) page.

## The scoped Studio

There is one Studio, not a separate portal per role. When you sign in with an
[owned key](/concepts/owned-keys) — a capability-scoped credential rather than a
full-privilege one — the shell renders from that key's **capability projection**
(`GET /api/auth/me`): the sidebar trims to the features the key can reach, each
list slices to what its scopes cover, and the data-bearing inboxes filter to the
key's own identity. Nothing is hidden by the client; the projection is the same
derived, jq-exact view the request gate enforces, so the UI never shows a door
the server would then deny.

The screen below is the same Tools screen as above, but signed in as an owned key:
the sidebar carries only Tools, Interactions, Notifications, and Settings — the
operator surfaces (Dashboard, System, Marketplace, and the rest) are gone. This
key's projection reaches the tool surface, so its catalog is the full list; the
scoping visible here is the **trimmed navigation**, and the genuinely sliced views
are the identity-filtered inboxes below. A key whose scopes did not reach the tool
surface would list fewer tools — or carry no Tools link at all.

![The Tools screen under a capability-scoped owned key, with a trimmed sidebar.](https://mintcdn.com/tai42/J3EwUppE79g8gCm1/images/studio/scoped-tools-light.png?fit=max\&auto=format\&n=J3EwUppE79g8gCm1\&q=85\&s=2a49baee1913b21c8eb8f6360466b5bc)

The scoped Tools screen under an owned key: the operator surfaces are gone from the sidebar; this key reaches the tool surface, so its catalog is the full list.

The Interactions and Notifications inboxes are **isolated by identity**. A
restricted key sees only messages [addressed to its own key
identity](/concepts/owned-keys#data-isolation) by `audience` — the pending questions
and notifications keyed on that key itself (its own island, not shared with sibling
keys under the same owner), never another identity's slice and never an operator's
broadcast.

![The Interactions inbox under an owned key, showing only the questions addressed to this identity.](https://mintcdn.com/tai42/svAMgtenosCg9O5X/images/studio/scoped-interactions-light.png?fit=max\&auto=format\&n=svAMgtenosCg9O5X\&q=85\&s=e0f5efe77c5571dbff006a97e850c483)

The scoped Interactions inbox: only the questions addressed to this owned key's identity.

![The Notifications inbox under an owned key, showing only the notifications addressed to this identity.](https://mintcdn.com/tai42/iRrtHiBZz_SZ94au/images/studio/scoped-notifications-light.png?fit=max\&auto=format\&n=iRrtHiBZz_SZ94au\&q=85\&s=de1f349b32cf8f9e9e99037329d5afaa)

The scoped Notifications inbox: only the notifications addressed to this owned key's identity.

You hand an owned key to another device without exposing the secret by minting it
from the [API-keys](/studio/api-keys) tab and turning it into a one-time QR
**claim link** in the create dialog. The [owned-keys guide](/guides/owned-keys)
walks the full flow.

![The API-keys create dialog turning a newly minted key into a one-time QR claim link.](https://mintcdn.com/tai42/GIUznzIs4DR40qfu/images/studio/mint-claim-link-light.png?fit=max\&auto=format\&n=GIUznzIs4DR40qfu\&q=85\&s=d0c20e26cbb2e86613ea5d64e7b7a5ba)

The mint dialog's claim-link step: a newly minted key rendered as a one-time QR claim link.

## The rest of the sidebar

The remaining links follow the same shape — a master list on the left, a detail
or editor on the right:

* **Presets** *(Capabilities)* — [versioned tool-wraps](/concepts/presets) and their
  version history; each preset also renders and edits its
  [tool-organization](/concepts/tool-organization) display name and tags (folder
  navigation and hide controls stay on the Tools screen). See
  [Presets](/studio/presets) for the create dialog and the fixed-kwargs editor.
* **Hooks** *(Triggers)* — [event hooks](/concepts/hooks) wired to the server.
* **Scheduling** *(Triggers)* — [scheduled tool runs](/concepts/triggers-and-webhooks).
* **Interactions** *(Activity)* — the [human-in-the-loop](/concepts/interactions)
  inbox of pending questions.
* **Notifications** *(Activity)* — the [notifications](/concepts/notifications) inbox.
* **Settings** *(Administration)* — server configuration, environment values, and API
  keys (see [Admin console](/studio/admin-console) and [API keys](/studio/api-keys)).
  An environment save of a recycle-class setting shows the worker recycle it rolled.
  A **Reload config** control re-reads env and re-initializes the deployment from its
  manifest in place, applied on the serving worker and broadcast to the fleet; a worker
  whose reload left a recycle-class setting waiting for a restart is listed with it.
* **Storage** *(Administration)* — the [stored-resource](/concepts/storage-and-resources)
  backend surface.

Several of these surfaces are backed by Redis or Postgres in the running server;
a screen whose store is not provisioned says so plainly instead of showing a
fabricated state.

See the [Studio SDK reference](/reference/studio-sdk/index) for the components
and hooks these screens are built from.