Documentation
¶
Overview ¶
Package presets defines agent presets: named bundles of session config values (mode, model, effort, …) a client applies when creating or steering a session.
The host serves presets and stores user-created ones; it NEVER applies them to a request — the client is the only thing that sends config (policy lives with the caller). The one thing the host does with config is REMEMBER it: the session row keeps the last-applied config, and a rehydrated backend re-asserts it after resume. That is restoration of caller policy across an agent-process rebuild, not the host choosing policy. Built-ins arrive via $CLANK_BUILTIN_PRESETS, serialized from the typed sets below by whatever provisioned the host — the one thing that knows the environment's blast radius. Same pattern as CLANK_TEMPLATES: Go values in one file, marshaled only at the process boundary.
Every config value below is a value id the agent ADVERTISES (measured against claude-agent-acp 0.61.0, codex-acp 1.1.7, opencode 1.17.18 — re-probe on adapter bumps). Keys a backend cannot express truthfully are absent: codex and opencode advertise no "default" alias for model, so their presets leave the model knob untouched and the agent's own config governs (visible to clients as the option's current value).
Index ¶
Constants ¶
const ( BuiltinDefaultPrefix = "builtin-default-" BuiltinPlanPrefix = "builtin-plan-" )
Builtin preset IDs. The Default preset doubles as the create-time validation contract: its config KEYS are the required keys for that backend (see RequiredKeys).
Variables ¶
This section is empty.
Functions ¶
func EnvValue ¶
EnvValue serializes presets for $CLANK_BUILTIN_PRESETS (provisioner → host boundary). An empty list serializes to "" — indistinguishable from an unset env, since Parse treats both as "not declared" (callers then fall back to Workstation()). json.Marshal of []Preset (strings, a map[string]string, and a bool) cannot fail, so the shape is total — same precedent as provisioner.TemplatesEnvValue.
func RequiredKeys ¶
func RequiredKeys(builtins []Preset, bt agent.BackendType) []string
RequiredKeys returns the create-time required config keys per backend: exactly the keys of that backend's built-in Default preset. Data-defined strictness — a create missing any of them fails loudly (the host never fills values in), and a client following the preset flow satisfies it by construction.
Types ¶
type Preset ¶
type Preset struct {
// ID is stable and unique per host. Built-in ids are prefixed
// "builtin-" and reserved: user presets may not claim them.
ID string `json:"id"`
Name string `json:"name"`
Backend agent.BackendType `json:"backend"`
// Config is applied verbatim by clients as StartRequest/
// SendMessageOpts config: agent-advertised option id → value id.
Config map[string]string `json:"config"`
// Instructions is reserved for preset-carried system-prompt text
// (rides the per-adapter guidance channels, not config options).
// Serialized when present so older hosts round-trip it untouched.
Instructions string `json:"instructions,omitempty"`
// Builtin marks host-shipped presets: immutable, undeletable,
// duplicate-to-edit.
Builtin bool `json:"builtin,omitempty"`
}
Preset is one named config bundle for one backend.
func DefaultFor ¶
func DefaultFor(ps []Preset, bt agent.BackendType) *Preset
DefaultFor returns the backend's built-in Default preset from ps, or nil when absent. The Default preset is the bundle a client applies verbatim when the user picked nothing, and its keys double as the create-time required keys (RequiredKeys).
func Parse ¶
Parse decodes $CLANK_BUILTIN_PRESETS. "" means "not declared" — callers fall back to Workstation(). Every entry is validated and forced Builtin, so a provisioner cannot ship mutable or malformed built-ins.
func Sandbox ¶
func Sandbox() []Preset
Sandbox returns the built-in presets for disposable environments (cloud sandboxes): run without permission prompts.
func Workstation ¶
func Workstation() []Preset
Workstation returns the built-in presets for machines with real data (a laptop, a self-hosted box): the agent's guarded stance, no prompt spam. The default set when a host declares nothing.
Source Files