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
PRESET_INPUT_MAP_ANNOTATION
tai42_contract.presets.models.PRESET_INPUT_MAP_ANNOTATION
input_map: its input document, $fixed and result rule.
PRESET_OUTPUT_MAP_ANNOTATION
tai42_contract.presets.models.PRESET_OUTPUT_MAP_ANNOTATION
output_map: its input document and result rule.
CarryForward
tai42_contract.presets.models.CarryForward
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 /
input_map / output_map 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
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.
input_map and output_map are optional jq programs. With an input_map the
caller’s object (validated against input_schema, which the map requires) is mapped
to the base tool’s arguments, with the stored fixed_kwargs readable as $fixed;
the mapped object is merged with fixed_kwargs and a key both set is refused, so a
fixed value is never overridden. The base tool’s result then passes the output stage:
output_map maps it, and output_schema validates what the map produced (or the
raw result when there is no map). An output map never runs over a result that carries
a secret. A str map is the jq program itself; a
TemplatedText is rendered to the program.
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, dropping input_schema would silently un-enforce the
structured input, and dropping input_map or output_map would silently
change what the base tool receives or what the caller gets back.
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
PresetError
tai42_contract.presets.errors.PresetError
name.
Attributes
PresetExistsError
tai42_contract.presets.errors.PresetExistsError
name already exists.
PresetInputMap
tai42_contract.presets.models.PresetInputMap
input_map field type: a jq program (a str, or a TemplatedText rendered to one), annotated.
Every surface that stores, edits, validates or reads back a preset’s input map declares its field
(or flat parameter) with this type, so each generated schema carries the same expression annotation.
PresetInputSchemaSupport
tai42_contract.presets.models.PresetInputSchemaSupport
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
PresetNameConflictError
tai42_contract.presets.errors.PresetNameConflictError
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
name.
PresetOutputMap
tai42_contract.presets.models.PresetOutputMap
output_map field type: a jq program (a str, or a TemplatedText rendered to one), annotated.
Every surface that stores, edits, validates or reads back a preset’s output map declares its field
(or flat parameter) with this type, so each generated schema carries the same expression annotation.
PresetOutputStage
tai42_contract.preset_stages.PresetOutputStage
PresetParkStages
tai42_contract.preset_stages.PresetParkStages
answer: applied to the park’s answer before the driver’s continuation receives it.
terminal: applied to the resumed drive’s terminal result.
chained: applied to a chained run’s terminal before it fires along the routing with that chain key.
Each list is ordered innermost preset first.
Attributes
PresetSeed
tai42_contract.presets.models.PresetSeed
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, input_map / output_map 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
PresetSeedToolMeta
tai42_contract.presets.models.PresetSeedToolMeta
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
PresetSpec
tai42_contract.agent.base.PresetSpec
name follows PRESET_NAME_PATTERN. A base tool that interprets its fixed kwargs as a
nested document carries that document opaquely here.
Attributes
PresetStore
tai42_contract.presets.PresetStore
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
spec carries name/description/
base_tool/fixed_kwargs; extensions (the combos list) and the
optional output_schema / input_schema / input_map / output_map 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
save_version
tai42_contract.presets.PresetStore.save_version
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, input_schema, input_map and
output_map 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 value = 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
list_presets
tai42_contract.presets.PresetStore.list_presets
get_preset
tai42_contract.presets.PresetStore.get_preset
PresetNotFoundError if absent.
Parameters
get_active_kwargs
tai42_contract.presets.PresetStore.get_active_kwargs
fixed_kwargs.
Raise PresetNotFoundError if absent.
Parameters
list_versions
tai42_contract.presets.PresetStore.list_versions
is_current signal.
Raise PresetNotFoundError if the preset is absent.
Parameters
get_version
tai42_contract.presets.PresetStore.get_version
PresetVersionNotFoundError if that version does not exist.
Parameters
get_active_body
tai42_contract.presets.PresetStore.get_active_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
rollback
tai42_contract.presets.PresetStore.rollback
version (no data copy).
Raise PresetVersionNotFoundError if that version does not exist.
Parameters
soft_delete
tai42_contract.presets.PresetStore.soft_delete
PresetNotFoundError if absent.
Parameters
rename_preset
tai42_contract.presets.PresetStore.rename_preset
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
PresetVersionNotFoundError
tai42_contract.presets.errors.PresetVersionNotFoundError
version exists for preset name.
Attributes
PresetWriteValidator
tai42_contract.presets.PresetWriteValidator
preset_output_failed_outcome
tai42_contract.preset_stages.preset_output_failed_outcome
RunTerminalFailed and recorded whole; it names
the preset and the refusal text.
Parameters

