Preset compositions

An agent preset is a composition: the set of plugin parts a chat on that preset starts with. Presets that ship with DataMind Oda and presets you write are declared the same way, as one block of fields inside a composition, and Oda reads that declaration back to build a chat, list the preset and check whether it can compose a session. This page covers the fields a declaration carries, the row it sits under, and how to read what Oda reports about a composition. Editing a preset from the interface is on Create and edit agent presets, and choosing one for a chat is on Agent presets.

What a declaration carries

Field	Needed	What it sets
`id`	Yes	The preset's identity, in lowercase letters, digits and hyphens. Chats record this id, and your saved choices name it.
`plugins`	Yes	The rows the preset composes. Each row names a plugin, may carry that plugin's configuration, and can be declared off.
`name`	No	The label shown for the preset where presets are listed. Without one, the `id` is shown.
`description`	No	One sentence on what the preset is for, shown with the preset.
`order`	No	Where the preset sorts in the list: lower values come first, and a preset without an order sorts after those that have one.
`model`	No	The provider and model chats on this preset start on. Without one, chats start on the default model.

A declaration written down looks like this:

yaml

id: review
name: Review
description: Reviews changes with the shell only.
order: 10
model:
  provider: <provider>
  model: <model>
plugins:
  - name: <plugin>

id and plugins are the two required fields; the rest are optional.

The row a declaration sits under

One row carries it. A declaration travels as a single row in a composition, and by convention that row's id is preset-<id>: the preset review sits in a row named preset-review. The declarations that ship with Oda and the ones Oda writes when you create a preset in Settings both follow the convention.
Duplicate ids stop the load. Two declarations cannot share an id. A second row reusing one fails to load and reports Duplicate agent preset: <id>; the declaration already in place stays.
An override replaces the whole declaration. A composition change that targets an existing declaration replaces it as a whole, so restate id, plugins and every other field the preset should keep. A field you leave out is not inherited from the version it replaces.
A built-in declaration is never edited in place. A preset is created or changed by a composition that an installed bundle carries; to change a built-in preset, override its declaration.

Reading a composition

What Oda reads back from a composition is an inventory of rows: the plugin each row names and the state it is in. The same read also runs over a live composition, where each row has a phase as well.

On, off, or conditional. A row reads as on when nothing stands in its way, as off when the declaration or a group above it switches it off, and as conditional when its state comes from a condition. A condition can only be settled while the composition runs, so the list reports it instead of guessing an on or off.
Groups pass their state down. A group row is structure, not a part of its own: the list shows the rows inside it, and the group's state reaches them.
A live composition adds phases. When the rows come from a composition that is running, each row also reports the phase it has reached, and a row that never started or is still waiting for another part carries that reason.
An unreadable declaration leaves a reason. If a declaration's rows cannot be read at all, the preset keeps its place in the list carrying the reason it cannot compose a session, and no new chat starts on it until the declaration is fixed.

To follow a composition on your computer, open Settings > Built-in plugins: the Session plugins group is composed per session by agent presets, and Choose the agent preset to inspect follows another preset's composition (Built-in plugins).

Questions, answered

Where does a preset's declaration come from?

A preset is created or changed by a composition that an installed bundle carries; a change to a built-in preset arrives as an override of it. Installing a bundle runs its code on this computer, so it needs Full access or your approval (Plugins and MCP connections). Creating or editing your own preset in Settings writes its declaration for you (Create and edit agent presets).

Do I have to name the composition row `preset-<id>`?

It is a convention rather than a rule. The declarations that ship with Oda and the ones Oda writes for you both follow it; keep it unless you have a reason not to.

Can two presets use the same id?

No. An id belongs to one preset at a time. A second declaration that reuses one fails to load with Duplicate agent preset: <id>, and the declaration already in place stays. Give the new preset its own id.

If I change a preset that already exists, do my changes merge with it?

No. An override replaces the declaration as a whole, not field by field: restate id, plugins and every other field the preset should keep, because a field you leave out is not inherited.

What if my `plugins` list is malformed?

The declaration fails to load with the message for what is wrong:

A plugins field that is not a list of plugin rows reports the composition must be a top-level list of plugin rows.
A row with no plugin name reports row <n> names no plugin (a "name" string is required).
A declaration with no id reports Preset id must not be empty.

Can a preset be declared with no name or description?

Yes. name, description, order and model are all optional. A preset with no name is listed under its id, and adding a name later does not change that id.

How do I control where my preset appears in the list?

Give it an order. Lower values come first, a preset with no order sorts after those that have one, and presets that share a value fall back to their id.

Is a preset a boundary on what its plugins may do?

No. A preset is a composition, not a boundary: the plugins a declaration names run with Oda's own access to this computer. For the limits on what a chat may change, see Command sandboxing and approvals.

What happens when a declaration cannot be read?

Oda does not guess: the preset keeps its place in the list carrying the reason it cannot compose a session, and no new chat starts on it until the declaration is fixed.

Where do I see a preset's composition?

Open Settings > Built-in plugins and look at the Session plugins group. It is composed per session by agent presets, and Choose the agent preset to inspect follows another preset's composition; Built-in plugins covers that list and the states a row can show.