Documentation
¶
Overview ¶
Package config implements Strument's Starlark configuration surface and the direnv-style trust gate for project configs.
Index ¶
- Constants
- func DefaultTrustStorePath() (string, error)
- func DefaultUserConfigPath() (string, error)
- func SlugCore(slug string) string
- func TrustProject(projectRoot, trustStorePath string) (string, error)
- func ValidEnvAllowName(s string) bool
- type Check
- type Config
- type Model
- type Options
- type Provider
- type ReasoningDisplay
- type ReasoningMode
- type TrustStore
Constants ¶
const ( AdapterOpenAI = "openai" AdapterOpenRouter = "openrouter" )
Adapters recognized by provider(). "anthropic" is reserved (deferred).
const DefaultTrustHash = multihash.SHA2_256
DefaultTrustHash is the multihash code used for new records.
const DocsURL = "https://github.com/dbohdan/strument"
DocsURL is the documentation's home for someone who installed the binary and has no source tree to read it from.
const ProjectConfigName = ".strument.star"
ProjectConfigName is the project-root dotfile, untrusted by default.
const SandboxLandlock = "landlock"
SandboxLandlock is the only confinement mechanism Strument implements. It is a named string rather than a boolean because "sandboxed" is not one thing: a future macOS or Windows backend would be a different mechanism with different guarantees, and a config that says which one it got can be read years later and still mean something.
Variables ¶
This section is empty.
Functions ¶
func DefaultTrustStorePath ¶
DefaultTrustStorePath is $XDG_STATE_HOME/strument/trust, defaulting to ~/.local/state/strument/trust.
func DefaultUserConfigPath ¶
DefaultUserConfigPath resolves the user config location via os.UserConfigDir, which honors XDG_CONFIG_HOME.
func SlugCore ¶
SlugCore reduces a model slug to its core name: everything after the last "/" (dropping the provider prefix) and before the first ":" (dropping a ":variant" suffix, which can name a private endpoint). Falls back to the full slug when that reduction is empty. It is the default display name, and `strument model-config` reuses it as the dict-key alias.
func TrustProject ¶
TrustProject computes the project config's multihash and records it in the trust store; the `strument trust` command calls this.
func ValidEnvAllowName ¶
ValidEnvAllowName reports whether s is acceptable as an env_allow entry: a single non-empty word with no "=" (values always come from the real environment) and no quoting characters — the config and the /env command share this rule, and neither does shell-style unquoting, so a quoted string must fail rather than become a name with literal quotes in it.
Types ¶
type Check ¶
Check is one named verification command: an argv, never a shell string.
The name is what the model passes to the check tool, which is the point of naming them. The model never supplies a command, so there is nothing to classify and nothing to smuggle through — which is what lets checks run without the confirmation `bash` requires.
func ProjectChecks ¶
ProjectChecks returns the checks detected in root, in a fixed order. An empty root — no project this session — detects nothing.
type Config ¶
type Config struct {
Models map[string]*Model // alias -> model
Default string // must be a key of Models
// HistoryFile overrides the chat-history path ("" => the XDG default).
// A relative path is resolved against the project root by the caller.
HistoryFile string
// Proxy is the global fallback SOCKS5 proxy URL: it applies to
// model-config, URL scraping, and any provider that sets no proxy of its
// own ("" => no global proxy).
Proxy string
// Scraper, when non-empty, is an external command (argv, with %s marking the
// URL) run to fetch pages instead of the built-in HTTP scraper — the opt-in
// path for JavaScript-rendered pages. The global proxy does not apply to it.
Scraper []string
// Check is the project's named verification commands, in declared order.
// The `check` tool runs them by name; a run with no name runs all of them
// in order and stops at the first failure, so fast checks belong first.
Check []Check
// CheckAuto names the checks the harness runs on its own at the end of a
// turn that edited files, in the order given. Empty means the model is the
// only thing that ever runs a check.
CheckAuto []string
// ReasoningDisplay is how much of the model's thinking to show. The zero
// value shows all of it.
ReasoningDisplay ReasoningDisplay
// MaxSteps overrides the work-step budget per turn. 0 uses the built-in
// default (25). The budget is a checkpoint, not a wall: on exhaustion the
// user is shown what the turn has done and asked whether to keep going.
MaxSteps int
// MaxErrorReflections overrides the error-reflection budget per turn. 0
// uses the built-in default (3). An error reflection is the model
// recovering from its own mistake — a failed edit match, a bad shell
// command — and should stay rare.
MaxErrorReflections int
// Sandbox names the confinement mechanism: SandboxLandlock or "" for
// none. It defaults to Landlock on Linux and "" elsewhere, and when it is
// set it is a requirement rather than a preference — see doc/security.md.
Sandbox string
// SandboxWrite are extra absolute paths the sandbox permits writes under,
// on top of the project, the state directory, a temporary directory and
// the toolchain caches.
SandboxWrite []string
// ShellTimeout bounds one model-caused command, in seconds. 0 is unset
// (the coder's two-minute default); -1 is the config's `shell_timeout = 0`,
// meaning no limit. /run is never bounded — the user typed it.
ShellTimeout int
// GitSign is the commit-signing flag passed to `git commit`: "-S" to sign
// with the default key, "-S<keyid>" to pick one, "" for unsigned. It comes
// from the `git_sign` setting (a boolean or a key-id string).
GitSign string
// EnvAllow names environment variables to pass to model-run commands
// (the bash tool, checks, the scraper command) on top of the built-in
// default allowlist. See coder/envallow.go. Empty means defaults only.
// Matching is exact; prefixes are not expanded.
EnvAllow []string
}
Config is the host-facing result of the load pipeline.
func Load ¶
Load runs the config pipeline: user config, gated project config, whole-key merge, post-merge side_model resolution, validation.
func (*Config) CheckNames ¶
CheckNames lists the configured check names in declared order.
func (*Config) DefaultModel ¶
DefaultModel returns the model for the default alias.
type Model ¶
type Model struct {
Provider Provider
Slug string
DisplayName string // human-readable label; "" => derived from Slug
EditFormat string // "tool" | "diff" | "diff-fenced" | "whole"
SideModel *Model // non-nil after resolution (self if unset)
Reasoning string // request-side effort: "low"/"medium"/"high"; "off" disables; "" or "default" => provider default
ReasoningTag string // response-side inline tag to strip; "" => none
Temperature *float64
RepoMap bool
Cache bool // enable prompt-cache breakpoints (1h TTL)
Context int // input window tokens; 0 => unknown
MaxOutput int
InputCost *llm.Money // per-token USD (config declares per-million); nil => unknown (never fabricate cost)
OutputCost *llm.Money
ExtraParams map[string]any
// contains filtered or unexported fields
}
Model is one usable model declaration.
func (*Model) QualifiedSlug ¶
QualifiedSlug is the provider-qualified model slug: the provider's name (its adapter when unnamed) joined to the slug, e.g. "openrouter/xiaomi/mimo-v2.5" or "local/qwen/qwen3.6-27b". Shown wherever the user sees a slug, it makes an endpoint diagnosable at a glance — which provider is this model on? — and converges on aider's provider-prefixed model names.
func (*Model) ReadableName ¶
ReadableName is the human-facing model name used in commit trailers: the configured display_name, or the slug reduced to its core (see SlugCore).
func (*Model) RequestExtraParams ¶
RequestExtraParams merges provider-scoped and model-scoped extra_params, model over provider.
type Options ¶
type Options struct {
UserConfigPath string // "" => os.UserConfigDir()/strument/config.star
ProjectRoot string // "" => no project config discovery
TrustStorePath string // "" => DefaultTrustStorePath()
LookupEnv func(string) (string, bool) // nil => os.LookupEnv
Warn func(format string, args ...any) // nil => stderr
}
Options configures Load. Zero values pick the real environment.
type Provider ¶
type Provider struct {
Adapter string // "openai" | "openrouter"
BaseURL string // "" => adapter default
APIKey string
Name string
Proxy string // resolved SOCKS5 proxy URL; "" => direct (no proxy)
ExtraParams map[string]any // JSON-only, reserved keys rejected
}
Provider is a pure carrier of endpoint + dialect; no behavior inheritance.
type ReasoningDisplay ¶
type ReasoningDisplay struct {
Mode ReasoningMode
Lines int // meaningful only for ReasoningCapped
}
ReasoningDisplay is the `reasoning_display` setting: "full", a positive integer, or "off".
It is about a screen, not about a request. "off" hides the thinking; it does not stop the model producing it, and reasoning tokens are billed either way. The per-model reasoning="off" is what stops the spending. Keeping these apart matters because a project's .strument.star could otherwise change what a turn costs by way of a display preference.
type ReasoningMode ¶
type ReasoningMode int
ReasoningMode is what ReasoningDisplay does with a thinking block.
const ( // ReasoningFull shows the whole block. The default, because a plain text // stream has no way to unfold what it hid, so anything less makes the // transcript incomplete — which is a thing to choose, not to inherit. ReasoningFull ReasoningMode = iota // ReasoningCapped shows the first Lines lines and says how many it left. ReasoningCapped // ReasoningOff shows nothing, not even a marker. ReasoningOff )
type TrustStore ¶
type TrustStore struct {
// contains filtered or unexported fields
}
TrustStore is a file-backed trust database. The file lives in the user state dir and must not be synced between hosts.
func OpenTrustStore ¶
func OpenTrustStore(path string) (*TrustStore, error)
OpenTrustStore loads the store at path, treating a missing file as empty.
func (*TrustStore) IsTrusted ¶
func (ts *TrustStore) IsTrusted(absPath string, content []byte) bool
IsTrusted reports whether content at absPath matches its recorded digest. The recorded multihash decides the hash function (self-description), so records written under an older default keep verifying after a migration.
func (*TrustStore) Trust ¶
func (ts *TrustStore) Trust(absPath string, content []byte) error
Trust records (absPath, multihash(content)) under the current default hash and persists the store.
func (*TrustStore) TrustWithCode ¶
func (ts *TrustStore) TrustWithCode(absPath string, content []byte, code uint64) error
TrustWithCode records under an explicit multihash code; used by tests to simulate records from an older/newer default function.
Source Files