Skip to main content
The Presets screen manages 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.The Presets screen listing presets with their base tool, active version, tags, and extension counts.

The Presets screen: the list of presets with their base tool, active version, tags, and extension counts.

The list and detail

The list is a folder explorer rooted at All presets, with a breadcrumb and a list or card view, showing the Presets screen’s own view of the folder tree. Each row gives a preset’s name, base tool, description, active version, tags, and extension count, and each card shows the same fields (Active version N, Extensions N); each folder carries Rename, Move and Delete for a session allowed to make that change. A preset whose tool collides at boot is listed apart, in a Conflicted table below the explorer. A Filter presets box narrows the list to the presets whose name, display name or description contains the text, ignoring case, and tag chips (Filter presets by tag, with Untagged) narrow it by the presets’ overlay tags; the chips show once the overlay has loaded. The filter lives in the URL as ?q= and ?tags=, the same as on the Tools screen: the text is applied on Enter or when you leave an edited box, and opening a preset and coming back with the detail’s Back link keeps it. With no preset, the list shows No presets yet, or No active presets when every preset is conflicted, and any folders still show below that line with their actions. Selecting a row opens the preset’s detail. A link that names a preset (/presets?preset=<name>) opens the folder it is filed in, so its row shows selected in place. The detail shows the preset’s current body — base tool, fixed kwargs, output schema, input schema, input and output maps, and extension sets — and its version history. The detail’s Edit details dialog sets the preset’s display name, tags, and folder (“Where this preset is filed.”); 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, the ordered Extensions (see Extension sets), an optional Input schema (what callers send), an optional Input map (a jq program that turns the caller’s input into the base tool’s arguments, with $fixed holding the fixed kwargs), an optional Output schema, an optional Output map (a jq program that reshapes the base tool’s result before the output schema is checked), and the preset’s state binding. 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. An input map needs an input schema; the dialog shows the server’s verdict on the pairing and on each map through Validate and the submit feedback (see input and output maps).
The create-preset dialog showing the Input schema editor, the Input map and Output map jq fields, and the Output schema editor.The create-preset dialog showing the Input schema editor, the Input map and Output map jq fields, and the Output schema editor.

The create-preset dialog with an input schema, an input map and an output map authored.

The write controls show only for a caller whose access reaches them; anyone else reads the presets read-only. Without access to create, Create preset is replaced by the line “Creating presets is outside your access — presets are shown read-only.” Without access to save a version, New version is replaced by “Saving a new version is outside your access — this preset is shown read-only.” Edit details, Rename, Delete and each version’s Rollback are hidden for a caller whose access does not reach them.

Extension sets

The Extensions field holds the preset’s ordered extension sets: “Ordered extension sets applied to the preset tool.” Each set is built in the picker below the list, which groups the available extensions by kind (“Kind: <kind>”, with “(single-select)” on a kind that takes one extension per set). An extension that takes settings adds a “<name> settings” group, drawn from the settings schema the extension declares; a sealed environment setting reads “Env reference <NAME>, kept as written.”, and a schema the form cannot draw shows “The settings of <name> cannot be edited here: <reason>.” Add extension set stays disabled until the set has at least one extension, its settings are valid and it is not already in the list (“This extension set is already added.”). Each set in the list has Edit, which loads it back into the picker with Update extension set and Cancel edit, and Remove. An empty list reads “No extension sets.”; a set naming an extension the deployment no longer has is flagged “Unknown extension: <name>”. The same editor edits a tool’s extension sets on the Tools screen: the tool’s Extension sets card opens it with Edit extension sets, in a dialog titled “Edit extension sets — <tool>”.

Rename and delete

A preset’s name is its live tool name, so the server refuses a rename or a delete (409) while anything still uses the name: another preset, a schedule, a hook, a conversation route, a tool-extensions entry, a parked interaction, or a plugin’s reference (see Presets). Each dialog reads what holds the name when it opens and lists it, each holder a link to the screen where it is set; the action stays disabled while the list has entries. Holders the caller’s role cannot read show as one plain-text line per kind, such as “schedule: 1 not readable with your role”, not as links.
  • Rename opens “Rename preset — <name>” (“A preset’s name is its live tool name, so renaming rebinds the tool.”) with a New name field. Holders are listed under “Still used by — update these first:”.
  • Delete opens “Delete preset — <name>”, which asks “Delete the preset <name>?” and lists holders under “Still used by — remove these first:”. Its description says what goes: the stored preset and its tool (and its branch tools), or, for a quarantined record, only the record (“Removes the quarantined record. No live tool is touched.”).
A refusal at submit that names holders shows them in the same list, beside the refusal’s first line. Without access to read presets, each dialog shows “Checking what still uses this is outside your access — it needs read access to presets.” in place of the list, and the server decides at submit.
The Delete preset dialog listing a conversation route under Still used by, with the Delete button disabled.The Delete preset dialog listing a conversation route under Still used by, with the Delete button disabled.

A held delete: the confirm lists the conversation route that still uses the preset, as a link, with Delete disabled.

A preset the server cannot read

When the presets read fails on one stored preset row that the server cannot walk, the list and the detail show the server’s error without a Retry, since a retry would fail the same way, and a Delete preset ‘<name>’ button that removes the row. A caller whose access does not reach that delete reads “Deleting preset ‘<name>’ is outside your access — it needs write access to presets.” instead.

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.The create-preset dialog's fixed-kwargs editor in Fields view with a text row, a number row, and a secret-reference row.

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: 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 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.The fixed-kwargs editor in JSON view showing a secret reference as an !ENV marker.

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 ). 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 save-version dialog also carries the Input schema, Input map and Output map fields, seeded from the active version; a field you leave unchanged carries forward, and a field you empty is removed on the new version. The detail shows each one that is set as its own card beside Output schema. 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 for the full model and Configuration and secrets for how environment references are resolved.