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 at each use site becomes a literal true, but the constant STAYS here: it's added to IsGraduated, its Description is rewritten to say so, and it remains in All() so Recognized keeps returning true. That's what keeps an existing `--experimental <name>` silent rather than warning at every startup once the feature is default-on. Description returns "" only for names that were dropped entirely — a separate, later cleanup. New features land here as new Feature constants; the surface is intentionally small so adding one is one constant + one Description case. See docs/experimental.md for the full graduation checklist.
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 ¶
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 IsGraduated ¶ added in v0.4.0
func Recognized ¶
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 is a graduated no-op flag kept recognized for one // release so old configs don't warn or break. Background subagents are now // GA in the interactive TUI; the flag no longer gates behavior. BackgroundSubagents Feature = "background_subagents" // CodeMap enables the read-only repository structure map. It starts as an // outline-first graph index shared by the TUI and agent tools while the // dependency/impact-query UX settles. CodeMap Feature = "code_map" // Dispatch is still experimental: it enables the dispatch + integrate tools // for opt-in users while the decomposition + unattended-worker UX settles. Dispatch Feature = "dispatch" // DocumentGeneration enables the create_document agent tool: xlsx // generation (native, via excelize) and docx/pdf generation (via // pandoc, routed through the active command Sandbox). Opt-in first // because it's a brand-new tool surface — the content schema and the // pandoc/sandbox dependency story haven't been exercised on real // documents yet. DocumentGeneration Feature = "document_generation" // DocumentIngestion enables the read_document agent tool: bounded, // provenance-labeled text extraction for CSV, TSV, JSON, JSONL, XML, // and HTML files. Opt-in first because it's a brand-new tool surface // whose caps and format coverage haven't been exercised on real // files yet. DocumentIngestion Feature = "document_ingestion" // LSPCodeIntelligence is a graduated no-op flag kept recognized for one // release so old configs don't warn or break. LSP tools are now default-on; // server launch still happens lazily only when a semantic tool is used. LSPCodeIntelligence Feature = "lsp_code_intelligence" // Sandbox enables routing run_bash through a session-scoped podman // container (config.SandboxConfig.Backend = "podman") instead of the // host directly. Opt-in first because the container-lifecycle, // hardening-flag set, and credential-passthrough model haven't been // exercised outside this design's own review yet. Sandbox Feature = "sandbox" // SyntaxRanges is a graduated no-op flag kept recognized for one release // so old configs don't warn or break. The syntax_range tool is now // default-on for Go, TypeScript/JavaScript, Python, and Rust. SyntaxRanges Feature = "syntax_ranges" )
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 ¶
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 ¶
EnableFeature is the typed-name variant; useful when callers already have a Feature constant (e.g. tests).
func (*Set) EnabledNames ¶
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 ¶
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 ¶
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 ¶
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.
Source Files