experimental

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 24, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

Package experimental gates not-yet-stable features behind named flags so early adopters can iterate on them while the default experience stays stable. A feature lives here when:

  • The code is merged and tested, but
  • The UX / model behavior / API shape isn't settled, and
  • We want production users to encounter the feature only on deliberate opt-in.

Once a feature stabilizes the gate is removed (and Description returns "" for the removed name to keep old configs from erroring). New features land here as new Feature constants; the surface is intentionally small so adding one is one constant + one Description case.

Resolution sources (CLI > env > config; later wins on conflict):

  • --experimental <name> (repeatable on CLI)
  • $YOTTACODE_EXPERIMENTAL=name,… (comma-separated env)
  • experimental name = true (config.toml section)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Description

func Description(f Feature) string

Description returns a one-line human-readable description for the `/experimental` overlay and docs. Returns "" for unknown names so graduated-feature configs don't break — callers should treat an empty string as "no longer recognized" and continue.

func Recognized

func Recognized(name string) bool

Recognized reports whether name is in the current `All()` list. Unknown names should be tolerated (not erroring) but worth warning about — typos in `--experimental` shouldn't lock the user out, and removed features shouldn't break old configs. Caller decides what to do with the boolean.

Types

type Feature

type Feature string

Feature is a typed string used as the canonical identifier for an experimental capability. Strings are user-facing (they appear in flags, env vars, config sections) — pick names that are short, snake_case, and self-describing.

const (
	// BackgroundSubagents enables `run_in_background:true` on the
	// Agent tool. The async machinery is wired through (registry,
	// transcripts, get_subagent_result, completion notification),
	// but the model's reflexes around using bg subagents need
	// more polish — it tends to spawn one and then duplicate the
	// work itself. Gated until prompt steering reliably produces
	// the intended workflow.
	BackgroundSubagents Feature = "background_subagents"

	// Dispatch enables the `dispatch` + `integrate` tools: fan a batch
	// of subtasks out to subagents that run concurrently (write-capable
	// ones in isolated git worktrees), then merge their branches into one
	// integration branch. Distinct from BackgroundSubagents — dispatch
	// children run foreground/blocking, not fire-and-forget. Gated while
	// the decomposition + partition + merge UX settles.
	Dispatch Feature = "dispatch"
)

func All

func All() []Feature

All returns every recognized feature name in deterministic order. Used by the /experimental listing and by Parse's validation warnings. New features must be appended here when introduced.

type Set

type Set struct {
	// contains filtered or unexported fields
}

Set tracks which features are enabled in this session. Built once at startup from the three resolution sources (CLI/env/config) and passed by pointer to subsystems that need to gate behavior. Safe for concurrent read after construction; not safe for concurrent mutation (the startup wiring is single-threaded).

func NewSet

func NewSet() *Set

NewSet returns an empty Set. Callers typically follow up with Parse / Enable.

func (*Set) Enable

func (s *Set) Enable(name string)

Enable turns the named feature on. Unknown names are stashed in `unknown` (see UnknownNames) rather than rejected so the rest of the session continues normally.

func (*Set) EnableFeature

func (s *Set) EnableFeature(f Feature)

EnableFeature is the typed-name variant; useful when callers already have a Feature constant (e.g. tests).

func (*Set) EnabledNames

func (s *Set) EnabledNames() []string

EnabledNames returns the on-features sorted alphabetically. Used for the status-bar / startup-banner "experimental: X, Y, Z" surface and for the /experimental overlay.

func (*Set) IsEnabled

func (s *Set) IsEnabled(f Feature) bool

IsEnabled reports whether the given feature is on. Nil-safe so subsystems that haven't been wired yet (or test paths that don't construct a Set) can call this without guarding.

func (*Set) Parse

func (s *Set) Parse(commaList string)

Parse merges a comma-separated list of feature names into s. Whitespace around names is trimmed; empty entries are skipped; unknown names go to UnknownNames. Useful for env vars and any future single-string source.

func (*Set) UnknownNames

func (s *Set) UnknownNames() []string

UnknownNames returns the names Enable was asked to turn on that don't match a recognized feature. Caller can render these as a startup warning so users with typos or graduated features notice.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL