Skip to main content
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

PRESET_INPUT_MAP_ANNOTATION

tai42_contract.presets.models.PRESET_INPUT_MAP_ANNOTATION
The expression annotation of a preset input_map: its input document, $fixed and result rule.

PRESET_OUTPUT_MAP_ANNOTATION

tai42_contract.presets.models.PRESET_OUTPUT_MAP_ANNOTATION
The expression annotation of a preset output_map: its input document and result rule.

CarryForward

tai42_contract.presets.models.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 / 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
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. 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
Base for preset view failures, carrying the preset name. Attributes

PresetExistsError

tai42_contract.presets.errors.PresetExistsError
A preset named name already exists.

PresetInputMap

tai42_contract.presets.models.PresetInputMap
A preset 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
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

PresetNameConflictError

tai42_contract.presets.errors.PresetNameConflictError
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
No preset (or no active preset) named name.

PresetOutputMap

tai42_contract.presets.models.PresetOutputMap
A preset 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
A preset’s resolved output stage: the jq output map then the output JSON Schema, applied to a result. Attributes

PresetParkStages

tai42_contract.preset_stages.PresetParkStages
The output stages of the preset dispatches a park sits under, by where each one’s result reappears. 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
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, 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
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

PresetSpec

tai42_contract.agent.base.PresetSpec
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

PresetStore

tai42_contract.presets.PresetStore
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
Create a versioned 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
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, 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
List the active versioned presets.

get_preset

tai42_contract.presets.PresetStore.get_preset
Fetch a preset’s active record. Raise PresetNotFoundError if absent. Parameters

get_active_kwargs

tai42_contract.presets.PresetStore.get_active_kwargs
Return the active version’s baked fixed_kwargs. Raise PresetNotFoundError if absent. Parameters

list_versions

tai42_contract.presets.PresetStore.list_versions
List every version of the preset, each carrying its is_current signal. Raise PresetNotFoundError if the preset is absent. Parameters

get_version

tai42_contract.presets.PresetStore.get_version
Fetch one version. Raise PresetVersionNotFoundError if that version does not exist. Parameters

get_active_body

tai42_contract.presets.PresetStore.get_active_body
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

rollback

tai42_contract.presets.PresetStore.rollback
Re-point the active version to version (no data copy). Raise PresetVersionNotFoundError if that version does not exist. Parameters

soft_delete

tai42_contract.presets.PresetStore.soft_delete
Soft-delete the preset, keeping its version history (audit). Raise PresetNotFoundError if absent. Parameters

rename_preset

tai42_contract.presets.PresetStore.rename_preset
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

PresetVersionNotFoundError

tai42_contract.presets.errors.PresetVersionNotFoundError
No version version exists for preset name. Attributes

PresetWriteValidator

tai42_contract.presets.PresetWriteValidator

preset_output_failed_outcome

tai42_contract.preset_stages.preset_output_failed_outcome
The opaque FAILED outcome of a resumed run whose preset output stage refused the result. Carried on RunTerminalFailed and recorded whole; it names the preset and the refusal text. Parameters