diff --git a/internal/infrastructure/configuration/apply.go b/internal/infrastructure/configuration/apply.go index 5afdbdaa5..1261e3193 100644 --- a/internal/infrastructure/configuration/apply.go +++ b/internal/infrastructure/configuration/apply.go @@ -11,18 +11,8 @@ import ( "github.com/samcharles93/archie-core/internal/config" ) -// ApplyOverlayValues decodes overrides (a nested map of dotted-path -// values, as produced by the overlay store) into cfg using the same -// field-level precedence as a file overlay: only the keys present are -// replaced, every field the overlay omits keeps its existing value. -// -// This is the decode half of the runtime config overlay. The loader's -// ApplyOverlay wraps it with defaulting, validation and provenance; the -// dashboard PATCH path calls it on a copy of the published config and -// validates the materialised result before persisting. Either way the -// caller owns the cfg value -- pass a copy when the base must survive. -// -// overrides is read, never mutated. +// ApplyOverlayValues decodes a nested map of overrides into cfg, replacing +// only the keys present. overrides is not mutated. func ApplyOverlayValues(cfg *config.Config, overrides map[string]any) error { if len(overrides) == 0 { return nil @@ -30,19 +20,8 @@ func ApplyOverlayValues(cfg *config.Config, overrides map[string]any) error { return applyOverlayMapping(cfg, overrides) } -// applyOverlayFile layers the overlay file at path over target, with the same -// field-level precedence ApplyOverlayValues gives a map overlay, and reports the -// file's keys that nothing consumes. target is whatever the overlay addresses: -// the whole config for a main file, one sub-struct for a feature file. -// -// Both processed overlay forms go through it -- the single overlay file, and an -// overlay directory's main and feature files -- so neither can lose the fields of -// a map-valued entry it only partly addresses. A conf.d/*.yaml extra in an -// overlay directory does not: decodeExtra stores a whole file under -// cfg.Extra[name] and nothing reads that map, so there is no entry to fold into. -// Decoding an overlay into target directly replaces such an entry wholesale, -// which is how an overlay naming only services.state.target cleared the -// target_token the base file set. +// applyOverlayFile layers the overlay file at path over target and returns +// the file's unconsumed keys. func applyOverlayFile(path string, target any) ([]string, error) { mapping, err := decodeFileMapping(path) if err != nil { @@ -54,17 +33,8 @@ func applyOverlayFile(path string, target any) ([]string, error) { return overlayFileKeys(path, mapping, structTypeOf(target)) } -// applyOverlayMapping is the decode both overlay paths share: the fields each -// map-valued entry the overlay does not name are folded forward out of the -// entry target already holds, and the completed mapping is then decoded over it. -// -// yaml gives a struct field the field-level treatment ApplyOverlayValues -// promises, but a map VALUE is decoded into a fresh zero value: an entry the -// overlay only partially addresses would lose every field it does not name, so -// an operator changing services.state.target alone would silently drop -// target_token. Folding here, once, is what makes the promise hold for every -// map of structs (services, image.hosted, image.local, providers) instead of -// at each field's reader. +// applyOverlayMapping decodes doc over target, first carrying forward the +// fields of map entries that doc only partly sets. func applyOverlayMapping(target any, doc map[string]any) error { folded, err := foldOverrides(reflect.ValueOf(target), doc) if err != nil { @@ -90,13 +60,8 @@ func structTypeOf(target any) reflect.Type { return t } -// foldOverrides returns doc with the fields its map entries omit carried -// forward from the entries cfg already holds. It descends through structs, so -// {"image": {"hosted": {...}}} folds the same way as an override written at the -// top level. -// -// Only mapping-valued map entries need it: yaml keeps the entries a map of -// scalars does not name, and a struct field it does not name keeps its value. +// foldOverrides returns doc with the fields its map entries omit filled from +// cfg's existing entries, descending through structs. func foldOverrides(cfg reflect.Value, doc map[string]any) (map[string]any, error) { if cfg.Kind() == reflect.Pointer { if cfg.IsNil() { diff --git a/internal/infrastructure/configuration/decode.go b/internal/infrastructure/configuration/decode.go index 585234efe..4bc0c54fa 100644 --- a/internal/infrastructure/configuration/decode.go +++ b/internal/infrastructure/configuration/decode.go @@ -11,11 +11,8 @@ import ( "github.com/samcharles93/archie-core/internal/config" ) -// decodeConfigFileKeys decodes path into target, dispatching on extension, -// additionally returning target's undecoded top-level keys for a TOML -// source (see decodeTOMLKeys). A YAML source has no equivalent hook yet -// (plan-config-drift.md step 1 note) and always reports none -- unchanged -// behaviour, not a claim of completeness. +// decodeConfigFileKeys decodes path into target by extension and returns +// undecoded top-level keys for TOML files. func decodeConfigFileKeys(path string, target any) ([]string, error) { switch filepath.Ext(path) { case ".yaml", ".yml": @@ -27,11 +24,7 @@ func decodeConfigFileKeys(path string, target any) ([]string, error) { } } -// decodeFileMapping parses a configuration file into the nested mapping it -// carries, with no typed target. An overlay needs this shape: a typed decode -// cannot distinguish a key the file omits from a key it sets to the zero -// value, and that distinction is what carrying the fields of a partially -// addressed map entry forward is built on (see applyOverlayFile). +// decodeFileMapping parses a configuration file into an untyped nested map. func decodeFileMapping(path string) (map[string]any, error) { var doc map[string]any switch filepath.Ext(path) { @@ -53,13 +46,8 @@ func decodeFileMapping(path string) (map[string]any, error) { return doc, nil } -// decodeTOMLKeys decodes a TOML file into target, additionally -// returning the top-level dotted key paths present in the file that -// target did not consume (toml.MetaData.Undecoded()). A single decode -// target's undecoded set is not by itself "unknown" -- see Hazard 1 in -// .local/issue-tracker/plan-config-drift.md, one file can legitimately -// feed more than one target -- callers combine this with the other -// target's undecoded set before treating anything as a real unknown key. +// decodeTOMLKeys decodes a TOML file into target and returns the top-level +// keys target did not consume. func decodeTOMLKeys(path string, target any) ([]string, error) { meta, err := toml.DecodeFile(path, target) if err != nil { @@ -76,11 +64,7 @@ func decodeTOMLKeys(path string, target any) ([]string, error) { return keys, nil } -// decodeYAML decodes a YAML file into target. -// -// Every decode error names its file. The previous loadMainConfig returned -// bare yaml.Unmarshal and toml.DecodeFile errors, so a syntax error in one -// of several files gave no clue which one to open. +// decodeYAML decodes a YAML file into target. Errors name the file. func decodeYAML(path string, target any) error { data, err := os.ReadFile(path) if err != nil { @@ -93,17 +77,8 @@ func decodeYAML(path string, target any) error { } // decodeFeature decodes a feature file into the part of cfg it describes. -// -// Most feature files carry top-level keys matching Config fields and decode -// into cfg directly. Memory and tools are sub-structs whose keys sit at the -// top level of their own file rather than nested under a "memory:" or -// "tools:" key, so they decode into the sub-struct. -// -// An overlay layer's feature file is folded over the base layer, for the same -// reason and with the same precedence as a main overlay file. The keys that fold -// reports are dropped here: only a main file reports unknown keys today -// (decodeMain), and a feature file reporting a second, differently-shaped set -// would be a new surface rather than a fix to this one. +// Memory and tools files decode into their sub-structs. Overlay feature files +// fold over the base. func decodeFeature(cfg *config.Config, feature Feature, path string, layer Layer) error { target := any(cfg) switch feature { @@ -119,12 +94,7 @@ func decodeFeature(cfg *config.Config, feature Feature, path string, layer Layer return decodeYAML(path, target) } -// decodeExtra decodes an unrecognised conf.d/ file into cfg.Extra under name. -// -// Unlike the previous implementation this reports failures instead of -// skipping them: silently dropping a file the operator wrote, because it -// happened to be unreadable or malformed, presents as the setting simply not -// taking effect. +// decodeExtra decodes an unrecognised conf.d/ file into cfg.Extra[name]. func decodeExtra(cfg *config.Config, name, path string) error { var value any if err := decodeYAML(path, &value); err != nil { diff --git a/internal/infrastructure/configuration/defaults.go b/internal/infrastructure/configuration/defaults.go index a5b41a7d3..0145ad198 100644 --- a/internal/infrastructure/configuration/defaults.go +++ b/internal/infrastructure/configuration/defaults.go @@ -25,11 +25,7 @@ const ( defaultPullPolicy = "missing" defaultContainerImage = "ghcr.io/samcharles93/archie-agent:latest" - // defaultMaxResultChars bounds one tool result. It matches the 50KB the - // lifted workspace tools already truncate themselves at - // (tools/builtin.DefaultMaxBytes), so those stay the binding limit and - // only tools with no truncation of their own -- skill bodies, MCP - // results -- see a change. + // defaultMaxResultChars bounds one tool result. defaultMaxResultChars = 50_000 defaultWebFetchTimeout = 30 * time.Second @@ -55,15 +51,7 @@ const ( defaultHealthDependencyTimeout = 5 * time.Second ) -// applyDefaults fills in every absent value. It never reports an error and -// never rejects input. -// -// Defaulting and validation were previously interleaved: functions named -// applyXDefaults also returned validation errors, and functions named -// validateX quietly mutated the config. That made it impossible to answer -// "what did the operator actually set?" -- the only way to see the supplied -// input was to not call them. Splitting them means defaults can be applied, -// inspected, and reasoned about independently of whether the result is valid. +// applyDefaults fills every absent value. It never validates. func (l *Loader) applyDefaults(cfg *config.Config) { applyServiceDefaults(cfg) if cfg.Health.Listen == "" { @@ -85,14 +73,7 @@ func (l *Loader) applyDefaults(cfg *config.Config) { } // applyServiceDefaults fills each registered service's absent addresses from -// its registration. It iterates the registry rather than naming services, so a -// new service needs no branch here -- only its RegisterService call. -// -// A registered service always ends with an entry, so later code can read -// cfg.Services.Get(name) without distinguishing "absent section" from -// "section with every field defaulted". An empty registered Target is a -// service whose target the operator must supply, and stays empty for -// validation to reject rather than being defaulted to something dialable. +// its registration. An empty registered target stays empty for validation. func applyServiceDefaults(cfg *config.Config) { if cfg.Services == nil { cfg.Services = config.Services{} @@ -119,11 +100,7 @@ func applyMemoryDefaults(cfg *config.Config) { } } -// DefaultCapture returns the webhook capture endpoint's default settings. -// applyCaptureDefaults fills a decoded -// config with them; the UI process composes the same capture receiver and -// must produce the same effective values when it is driven by flags alone -// and no configuration file projected [capture] to it. +// DefaultCapture returns the default capture settings. func DefaultCapture() config.CaptureConfig { return config.CaptureConfig{ Retention: config.Duration(defaultCaptureRetention), @@ -164,17 +141,8 @@ func applyToolPolicyDefaults(cfg *config.Config) { cfg.Tools.Policy.MaxResultChars = defaultMaxResultChars } - // SpillDir is deliberately NOT defaulted. - // - // Spilling hands the model a file path to read back, and the read tool is - // confined to chat.workspace. A default under work_dir is outside that for - // any workspace narrower than the whole home directory, and always outside - // a task agent's worktree -- so the model would be given a path it cannot - // open and the result would be lost rather than displaced. Truncating - // inline at least shows the first part of the result and says so. - // - // An operator who wants spilling points this at a directory inside the - // workspace; startup warns when it is not (see cmd/archied). + // SpillDir is not defaulted: spilled results must be inside the read tool's + // workspace to be readable. applyWebFetchDefaults(cfg) } @@ -189,11 +157,7 @@ func applyWebFetchDefaults(cfg *config.Config) { } } -// DefaultWorkDir returns the work directory an unset work_dir would have been -// given. Callers that must fall back when a configured path turns out to be -// unusable use this so the fallback is the same location the operator would -// have got by saying nothing, rather than a second guess that only this -// caller knows about. +// DefaultWorkDir returns the default work directory. func DefaultWorkDir() string { return filepath.Join(xdgDataHome(), "archie", "work") } @@ -206,13 +170,8 @@ func DefaultConfigDir() string { return filepath.Join(xdgConfigHome(), "archie") } -// DefaultConfigPath returns the configuration file an archie binary reads when -// -config is not given. Every binary that asks a question about a deployment -// has to read this path to be answering about the same deployment, so the rule -// lives here once and the binaries take it from here. Deriving it a second way -// is what went wrong before: os.UserConfigDir is a plausible-looking source for -// the same value that disagrees with this one on darwin and for a relative -// $XDG_CONFIG_HOME. +// DefaultConfigPath returns the config file archie binaries read when +// -config is not given. func DefaultConfigPath() string { return filepath.Join(DefaultConfigDir(), "config.toml") } @@ -227,11 +186,7 @@ func (l *Loader) applyGeneralDefaults(cfg *config.Config) { cfg.WorkDir = expandHomePath(cfg.WorkDir) cfg.StateDir = expandHomePath(cfg.StateDir) cfg.Chat.Workspace = expandHomePath(cfg.Chat.Workspace) - // DatabaseURL has no default and is not path-expanded: it is a connection - // URL, not a file path. Empty means "not configured", which the State - // Store refuses at boot (fail closed) rather than a value this loader can - // invent -- a wrong default would point a production store at a database - // that does not exist. + // DatabaseURL has no default. if cfg.WorkDir == "" { cfg.WorkDir = filepath.Join(l.dataHome(), "archie", "work") } @@ -325,16 +280,8 @@ func applyDispatchDefaults(cfg *config.Config) { } } -// applyIdentityDefaults derives forge-appropriate commit emails wherever the -// operator omitted one, for both deployment shapes, and adopts a sole -// [[identities]] entry as the root single-identity values. -// -// The root fields are not merely the legacy single-identity shape: consumers -// that are inherently single-agent read them (the session curator is built with -// cfg.BotUser), so leaving the root empty beside exactly one identity is an -// empty address rather than an unused field, and every curated session is -// skipped for want of an agent. With two or more identities there is no single -// answer, so the root is left alone for the operator to name deliberately. +// applyIdentityDefaults fills omitted commit emails and copies a sole +// [[identities]] entry into the root single-identity fields. func applyIdentityDefaults(cfg *config.Config) { if len(cfg.Identities) > 0 { for i := range cfg.Identities { diff --git a/internal/infrastructure/configuration/denied_keys.go b/internal/infrastructure/configuration/denied_keys.go index 7f0a00649..be91da7c9 100644 --- a/internal/infrastructure/configuration/denied_keys.go +++ b/internal/infrastructure/configuration/denied_keys.go @@ -1,13 +1,7 @@ package configuration // DeniedKeys are the config keys the runtime overlay may never set, mapped -// to the reason shown to the operator. database_url and state_dir are read -// before the overlay store can be opened, and work_dir pins the whole working -// layout. Enforced at write time (the -// API returns 4xx) and again in the overlay's Set, not silently dropped at -// read time. Owned here rather than in the overlay package so the webui -// config renderer can reference the policy without linking the overlay's -// SQLite store. +// to the reason shown to the operator. var DeniedKeys = map[string]string{ "database_url": "required for bootstrap; cannot be changed at runtime", "state_dir": "required for bootstrap; cannot be changed at runtime", diff --git a/internal/infrastructure/configuration/discovery.go b/internal/infrastructure/configuration/discovery.go index bafd0afb7..8dc513b72 100644 --- a/internal/infrastructure/configuration/discovery.go +++ b/internal/infrastructure/configuration/discovery.go @@ -11,13 +11,8 @@ import ( // confDirName is the subdirectory holding additional feature files. const confDirName = "conf.d" -// fileSet is the outcome of scanning one configuration directory: which file -// carries the daemon-level settings, which files carry recognised features, -// and which carry opaque extras. -// -// Scanning previously returned four bare values (two paths and two maps), -// which left the caller to remember that YAML wins over TOML and that extras -// are keyed by feature name. +// fileSet is the result of scanning a configuration directory: the main +// file, feature files and extras. type fileSet struct { mainYAML string mainTOML string diff --git a/internal/infrastructure/configuration/doc.go b/internal/infrastructure/configuration/doc.go index a06337b8e..5fd57d51e 100644 --- a/internal/infrastructure/configuration/doc.go +++ b/internal/infrastructure/configuration/doc.go @@ -1,33 +1,4 @@ -// Package configuration is the external configuration input boundary. -// -// It owns everything about how configuration arrives: locating files, -// decoding TOML and YAML, applying base/overlay precedence, resolving -// environment and secret references, defaulting absent input, validating -// what was supplied, and recording where each value came from. -// -// It owns none of the behaviour those values describe. Deciding what a -// dispatch trigger or a retry budget *means* belongs to the domain that -// acts on it; this package only decides whether the operator supplied -// something usable, and says so clearly when they did not. -// -// # Why this package exists -// -// Loading used to live inside internal/config, alongside the runtime types -// every package imports. That made the shared model responsible for file I/O, -// so a package that merely wanted a settings struct also pulled in a TOML -// decoder, and defaulting, validation and decoding were interleaved in one -// function. -// -// # The temporary seam -// -// [Document.Config] is not that yet: it is the existing internal/config.Config, -// exposed here so this package can take over loading without every consumer -// changing at once. -// -// It is deliberately a named field rather than a bare return value so the -// compromise is visible at each use site. It should be replaced by typed -// per-domain sections once those domains own their settings; the condition -// for deleting it is that internal/config no longer exists. Until then, do -// not add behaviour to it, and do not treat its presence as licence to pass -// whole-application configuration into a domain. +// Package configuration loads configuration: locating files, decoding TOML +// and YAML, applying overlays, resolving references, defaulting and +// validating. package configuration diff --git a/internal/infrastructure/configuration/errors.go b/internal/infrastructure/configuration/errors.go index 6fbb387e4..4c68d868e 100644 --- a/internal/infrastructure/configuration/errors.go +++ b/internal/infrastructure/configuration/errors.go @@ -2,14 +2,7 @@ package configuration import "errors" -// Sentinel errors callers can match with errors.Is. Everything else this -// package returns is wrapped with the offending path via %w. -// -// The distinction that matters to a caller is whether the operator can fix -// the problem by editing a file (ErrInvalidInput) or whether the -// configuration could not be read at all (ErrNoConfigFile, ErrUnreadable). -// The previous code signalled all of these with fmt.Errorf strings prefixed -// "config: ", so a caller had to match on message text to tell them apart. +// Sentinel errors for errors.Is. Other errors are wrapped with the path. var ( // ErrInvalidInput reports configuration that decoded successfully but // describes something unusable -- an unknown enum value, a missing diff --git a/internal/infrastructure/configuration/loader.go b/internal/infrastructure/configuration/loader.go index ec996ef20..952922fa7 100644 --- a/internal/infrastructure/configuration/loader.go +++ b/internal/infrastructure/configuration/loader.go @@ -26,13 +26,7 @@ type Document struct { // Provenance lists the files that produced Config, in precedence order. Provenance Provenance - // UnknownKeys lists dotted TOML key paths present in a loaded file that - // no decode target consumed (e.g. "containers.max_concurrancy" for a - // misspelled max_concurrency) -- present so a typo'd key is visible - // instead of silently parsing, validating and doing nothing. Sorted - // and de-duplicated. A missing key that a YAML config source carries - // is not yet detected here (plan-config-drift.md step 1 note); this - // is TOML-only for now. + // UnknownKeys lists sorted TOML key paths no decode target consumed. UnknownKeys []string } @@ -77,13 +71,8 @@ func xdgDataHome() string { return filepath.Join(home, ".local", "share") } -// xdgConfigHome returns $XDG_CONFIG_HOME, falling back to ~/.config, and -// finally to a relative path when the home directory is unknowable. -// -// os.UserConfigDir is the XDG-spec-shaped function and is deliberately not -// used: it resolves to ~/Library/Application Support on darwin and returns an -// error rather than a relative path for a relative $XDG_CONFIG_HOME, so two -// archie processes would read two different configuration files. +// xdgConfigHome returns $XDG_CONFIG_HOME, else ~/.config, else a relative +// path. func xdgConfigHome() string { if dir := os.Getenv("XDG_CONFIG_HOME"); dir != "" { return dir @@ -139,25 +128,14 @@ func validateOverlayPath(overlayPath, basePath string, baseIsDir bool) error { return nil } -// Overlay loads basePath, then decodes overlayPath into the same value so -// only the fields the overlay sets are replaced -- every field it omits keeps -// the base value. This lets a deployment-specific file (config.docker.toml) -// declare only what differs instead of restating the whole schema. An empty -// overlayPath is equivalent to [Loader.File]. +// Overlay loads basePath, then replaces only the fields overlayPath sets. An +// empty overlayPath is equivalent to File. func (l *Loader) Overlay(basePath, overlayPath string) (*Document, error) { return l.overlayFile(basePath, overlayPath) } -// ApplyOverlay decodes the runtime config overlay (a nested map of -// dotted-path values from the overlay store) into a copy of doc with the -// same field-level precedence as a file overlay, records the overlay -// origin, then applies defaults and validates. It is used at boot and on -// reload to layer dashboard-edited overrides over the file config. -// -// ApplyOverlay never mutates its input: the returned Document owns fresh -// copies of the Config and the provenance chain, so a decode or -// validation failure leaves the caller's document (and whatever it was -// published from) exactly as it was. +// ApplyOverlay layers runtime overrides over a copy of doc, then defaults and +// validates. doc is not mutated. func (l *Loader) ApplyOverlay(doc *Document, overrides map[string]any) (*Document, error) { next := *doc next.Config = doc.Config.Clone() @@ -208,15 +186,8 @@ func (l *Loader) overlayFile(basePath, overlayPath string) (*Document, error) { return l.finalize(doc, validateBootstrap) } -// overlayFileKeys reports the keys of an overlay file that nothing consumes. It -// has two sources, because the file's own decode and the fold's apply decode do -// not match keys the same way: TOML accepts a key that differs only in case, -// while the yaml decode the fold uses does not. A key only the file's decode -// matches would therefore be consumed by the report below and dropped in -// silence by the apply, so the apply's own view of the mapping is unioned in. -// -// The second decode here is deliberate: it is what carries TOML's Undecoded() -// view of the file, which the raw mapping cannot report (it consumes every key). +// overlayFileKeys returns the overlay file's keys that neither the TOML +// decode nor the overlay apply consumes. func overlayFileKeys(path string, mapping map[string]any, target reflect.Type) ([]string, error) { decoded, err := decodeConfigFileKeys(path, reflect.New(target).Interface()) if err != nil { @@ -225,11 +196,7 @@ func overlayFileKeys(path string, mapping map[string]any, target reflect.Type) ( return append(decoded, unmatchableKeys(mapping, target)...), nil } -// unmatchableKeys returns the dotted paths of the keys in mapping that the fold's -// yaml decode cannot match to a field of target. It descends the way foldOverrides -// does -- through structs and through string-keyed maps of structs -- so it sees -// the same keys the apply does. A slice of tables is not descended: the yaml -// decode replaces it wholesale, so anything inside it is a value, not a key. +// unmatchableKeys returns the keys in mapping that match no field of target. func unmatchableKeys(mapping map[string]any, target reflect.Type) []string { var out []string for key, value := range mapping { @@ -273,11 +240,8 @@ func prefixed(prefix string, keys []string) []string { return keys } -// unknownKeys returns the keys present in both a and b: one config file -// feeds more than one decode target (&doc.Config and &doc.Scheduling), so -// a key legitimately owned by one target decodes cleanly there and only -// shows up in the other target's undecoded set. Only a key neither target -// consumed is a real unknown key (Hazard 1, plan-config-drift.md). +// unknownKeys returns the keys present in both a and b, i.e. consumed by +// neither decode target. func unknownKeys(a, b []string) []string { if len(a) == 0 || len(b) == 0 { return nil @@ -295,13 +259,8 @@ func unknownKeys(a, b []string) []string { return out } -// unregisteredServiceKeys reports [services.] sections naming a service -// nobody registered. -// -// Undecoded() cannot see these. Services is a map, so TOML decodes any section -// under [services] into it successfully, and a typo'd [services.gatway] would -// load clean where the previous struct form reported it. The registry is the -// authority on which names exist, so ask it. +// unregisteredServiceKeys returns [services.] sections for unregistered +// services. func unregisteredServiceKeys(services config.Services) []string { var out []string for name := range services { @@ -331,7 +290,7 @@ func sortedUnique(keys []string) []string { return out } -// Dir loads configuration from a directory tree: +// Dir loads configuration from a directory: // // config.yaml daemon-level settings // config.gateway.yaml chat channels and platforms @@ -341,13 +300,8 @@ func sortedUnique(keys []string) []string { // config.identities.yaml identity settings // conf.d/*.yaml additional feature files // -// A missing feature file means the feature is absent, not an error. Legacy -// config.toml is the fallback when config.yaml is absent; YAML wins when -// both exist. -// -// When overlayDir is non-empty its files are applied on top of baseDir, with -// the same field-level precedence as [Loader.Overlay]. The overlay directory -// need not contain a main config. +// Missing feature files are fine. config.toml is used when config.yaml is +// absent. A non-empty overlayDir is applied on top. func (l *Loader) Dir(baseDir, overlayDir string) (*Document, error) { doc := &Document{} @@ -428,16 +382,7 @@ func (l *Loader) decodeMain(doc *Document, path string, isYAMLFile bool, layer L return nil } -// finalize applies defaults, then validates. The order matters: validation -// judges the defaulted configuration, including values the operator never -// wrote. -// -// validate is a parameter because the two kinds of caller produce different -// documents. Every file source ([Loader.File], [Loader.Overlay], [Loader.Dir]) -// produces a BOOTSTRAP document and passes validateBootstrap: the settings the -// control plane owns are layered over it later, so a stale value in one of them -// must not fail the load. [Loader.ApplyOverlay] layers overrides onto a -// document that is already effective, so it passes [Validate]. +// finalize applies defaults, then validate. func (l *Loader) finalize(doc *Document, validate func(*config.Config) error) (*Document, error) { doc.UnknownKeys = sortedUnique(append(doc.UnknownKeys, unregisteredServiceKeys(doc.Config.Services)...)) l.applyDefaults(&doc.Config) diff --git a/internal/infrastructure/configuration/provenance.go b/internal/infrastructure/configuration/provenance.go index c05469ba0..2cf3a1fcf 100644 --- a/internal/infrastructure/configuration/provenance.go +++ b/internal/infrastructure/configuration/provenance.go @@ -39,12 +39,7 @@ func (o Origin) String() string { return fmt.Sprintf("%s (%s %s)", o.Path, o.Layer, o.Role) } -// Provenance is the ordered list of files that produced a configuration, -// earliest first, so a later entry overrides an earlier one. -// -// Nothing recorded where a value came from before. With overlays, feature -// files and conf.d/ all able to set the same field, "which file set this?" -// was answerable only by re-deriving the precedence rules by hand. +// Provenance lists the files that produced a configuration, earliest first. type Provenance struct { Origins []Origin } diff --git a/internal/infrastructure/configuration/soul.go b/internal/infrastructure/configuration/soul.go index 3039bf567..e1be39755 100644 --- a/internal/infrastructure/configuration/soul.go +++ b/internal/infrastructure/configuration/soul.go @@ -39,11 +39,7 @@ type SoulSeedResult struct { Action SoulSeedAction } -// ConfigDir resolves the configuration directory for a selected config path: -// the path itself when it is a directory, otherwise the directory containing -// the selected file. It is how the SOUL file, which sits beside the config, -// follows an explicitly selected `-config` file as well as the default -// directory. +// ConfigDir returns configPath if it is a directory, else its parent. func ConfigDir(configPath string) string { if info, err := os.Stat(configPath); err == nil && info.IsDir() { return configPath @@ -56,18 +52,8 @@ func SoulPath(configPath string) string { return filepath.Join(ConfigDir(configPath), SoulFilename) } -// SeedSoul writes the starter SOUL into the configuration directory when no -// file exists and leaves an existing file untouched. It never overwrites a user -// edit, including an empty file. -// -// The check is content, not provenance, because the only durable copy of a -// file-owned SOUL is the file itself: an operator who edited it by hand leaves -// no writer identity to consult, so a body that differs from the build's -// shipped document is treated as theirs. -// -// The caller owns the decision to seed at all. A failure is returned rather -// than suppressed, because whether a missing starter is fatal belongs to the -// caller that needs the file, not to the seeder. +// SeedSoul writes the starter SOUL file when none exists. It never +// overwrites an existing file. func SeedSoul(configPath, shipped string) (SoulSeedResult, error) { dir := ConfigDir(configPath) if err := os.MkdirAll(dir, 0o700); err != nil { diff --git a/internal/infrastructure/configuration/validate.go b/internal/infrastructure/configuration/validate.go index a3b30d72a..0153004b7 100644 --- a/internal/infrastructure/configuration/validate.go +++ b/internal/infrastructure/configuration/validate.go @@ -38,34 +38,8 @@ var ( memoryEngines = []string{memoryEngineBuiltin} ) -// Validate judges a configuration a process will run with -- every check that -// can reject one -- against a config.Config value already built in memory, e.g. -// by archied setup before it has written anything to disk. It is a superset of -// what [Loader] applies to a file (validateBootstrap): a check over a setting -// the control plane owns belongs here and not there, so that a stale TOML value -// cannot fail a process's startup. -// -// It judges an EFFECTIVE document: the bootstrap file with every setting the -// control plane owns layered over it. That layering happens at exactly one -// place, boot.runtimeConfig (internal/app/archied/control_plane.go), which runs -// this afterwards; the daemon and the Gateway both go through it, and the -// readiness config probe re-runs it against the running value. A database value -// that will not validate therefore stops the process rather than starting it -// degraded. -// -// A plain file document is judged by validateBootstrap instead: see the split -// there for why the loader must not apply this to it. -// -// Like validate, it does not apply defaults. Several checks (dispatch.trigger, -// forge.type) only pass once a default has been filled -// in, and defaulting is currently unexported ((*Loader).applyDefaults). A -// cfg built by hand, with those fields left zero-valued, will fail -// validation that a config loaded through [Loader.File] would pass. Callers -// that build a config directly (rather than decoding one through a Loader) -// must fill in the same defaults themselves, or -- the safer option, since -// it can't drift from what the real load path does -- render the config to -// TOML and load it back through a Loader instead of calling Validate on the -// in-memory value directly. +// Validate checks an effective configuration, including settings the control +// plane owns. It does not apply defaults. func Validate(cfg *config.Config) error { return validate(cfg) } @@ -79,19 +53,8 @@ func validate(cfg *config.Config) error { return validateDatabaseOwned(cfg) } -// validateBootstrap reports the first problem in the settings a bootstrap -// document still owns: the file config a process reads before it can reach the -// State Store. [Loader] applies this to every file source. -// -// It deliberately omits the settings the control plane stores, because a stale -// TOML value in one of them must not be able to fail a process's startup. -// archie-state-store resolves its file config and seeds the control-plane -// resources from that same document on a fresh database, and a seed it cannot -// validate is skipped rather than fatal (controlplane.Server.ImportConfig), so -// a check left here is a check that can still block it. Those checks live in -// validateDatabaseOwned and run on the effective document instead -- which is -// where the process that uses the value refuses it, and where the operator's -// fix is the file again. +// validateBootstrap checks the settings a file configuration still owns, +// skipping those the control plane stores. func validateBootstrap(cfg *config.Config) error { if err := validateForgeIntake(cfg); err != nil { return err @@ -111,14 +74,8 @@ func validateBootstrap(cfg *config.Config) error { return validateCapture(cfg) } -// validateDatabaseOwned reports the first problem in a setting the control -// plane owns. Each check below judges a field that a control-plane resource is -// seeded from and replaces wholesale: providers (provider-settings), -// poll_interval and dispatch (scheduling-policy), containers -// (container-runtime-policies), and the repository lists -// (repository-policies). It runs on the effective document, after that -// replacement, which is the only point at which the value being judged is the -// value a process will use. +// validateDatabaseOwned checks the settings the control plane owns: +// providers, scheduling, containers and repositories. func validateDatabaseOwned(cfg *config.Config) error { if err := validateDispatch(cfg); err != nil { return err @@ -159,12 +116,7 @@ func validateMemory(cfg *config.Config) error { return nil } -// validateCapture rejects negative capture settings. applyDefaults fills -// every zero value with a positive default, so this only fires on an -// explicit negative value -- which would make time.Duration/AddDate math -// and the token-bucket rate limiter behave nonsensically (e.g. a negative -// retention window would prune every row on every insert, including the one -// just written). +// validateCapture rejects negative capture settings. func validateCapture(cfg *config.Config) error { if cfg.Capture.Retention < 0 { return fmt.Errorf("%w: capture.retention must not be negative", ErrInvalidInput) @@ -184,12 +136,7 @@ func validateCapture(cfg *config.Config) error { return nil } -// validatePollInterval rejects a non-positive poll interval. -// applyDefaults fills PollInterval == 0 with the default, so this only -// fires on an explicit negative value -- which would panic -// time.NewTicker/Reset in the daemon's poll loops, at boot and (worse) -// on a SIGHUP reload mid-run, when the edit that broke it is no longer -// fresh in the operator's mind. +// validatePollInterval rejects a negative poll interval. func validatePollInterval(cfg *config.Config) error { if cfg.PollInterval <= 0 { return fmt.Errorf("%w: poll_interval must be positive", ErrInvalidInput) @@ -197,13 +144,8 @@ func validatePollInterval(cfg *config.Config) error { return nil } -// validateDispatch rejects a "label" or "either" trigger left with no label -// to match. GitHub's issues-list API treats an empty label filter as no -// filter at all and returns every open issue in the repo -- a live incident -// (GH#445) queued 124 unrelated issues in one poll cycle this way, after -// [dispatch.labels] (a different field, mapping task states to their own -// labels) was configured while the actual trigger-match label was left -// blank. +// validateDispatch rejects a "label" or "either" trigger with no label: an +// empty label filter matches every open issue. func validateDispatch(cfg *config.Config) error { if !DispatchTriggerValid(cfg.Dispatch.Trigger) { return fmt.Errorf("%w: dispatch.trigger %q (want %s)", ErrInvalidInput, cfg.Dispatch.Trigger, list(dispatchTriggers)) @@ -214,27 +156,13 @@ func validateDispatch(cfg *config.Config) error { return nil } -// DispatchTriggerValid reports whether trigger names a discovery rule the daemon -// can poll with. It is exported because the scheduling-policy resource validator -// (internal/app/controlplane) judges the same field: that resource is seeded -// from cfg.Dispatch and replaces it wholesale once the database owns it, so a -// value this package rejects must not be storable, and a value it accepts must -// not be rejected there. One definition, both layers. +// DispatchTriggerValid reports whether trigger is a known discovery rule. func DispatchTriggerValid(trigger string) bool { return oneOf(trigger, dispatchTriggers) } -// validateForgeIntake checks the forge intake mode and that webhook intake has -// the secret and listen address it needs. An unset intake resolves to "poll" -// without mutating cfg, so Validate (which does not apply defaults) accepts a -// hand-built config the same way Loader.File accepts its on-disk form. -// -// It also refuses the intake settings that no code path reads: the ones on a -// [[identities]] entry, and a root webhook intake paired with [[identities]]. -// The receiver is single-identity by construction -// (bootstrap.setupForgeWebhook binds one dispatch predicate and one secret), -// so those two spellings could only have been accepted-and-ignored -- the root -// one silently downgrading to polling at startup. +// validateForgeIntake checks the intake mode and webhook settings, and +// rejects webhook intake with [[identities]] or on an identity. func validateForgeIntake(cfg *config.Config) error { intake := cfg.Forge.Intake if intake == "" { @@ -258,22 +186,11 @@ func validateForgeIntake(cfg *config.Config) error { return validateIdentityForgeIntake(cfg.Identities) } -// identityIntakes is the intake modes a [[identities]] entry may declare. -// "poll" is the whole list: the receiver reads the root [forge] block only, so -// a per-identity "webhook" would have no effect (see -// validateIdentityForgeIntake). Named separately from forgeIntakes so a -// rejection for a typo does not advertise modes the identity cannot have. +// identityIntakes are the intake modes an identity may declare. var identityIntakes = []string{config.ForgeIntakePoll} -// validateIdentityForgeIntake refuses the intake settings on a [[identities]] -// entry. IdentityConfig.Forge is the same type as the root [forge] block, so -// identities[N].forge.intake, .webhook_secret and .webhook_addr all DECODE -- -// but every read of them is of the root block (this file and -// bootstrap.setupForgeWebhook), and per-identity intake never reached even -// this function. An operator could therefore write a webhook intake that -// parsed, validated, and did nothing while the identity went on polling. -// Reject it at the source: intake per identity is a migration -// (internal/domain/workintake routing), not a setting. +// validateIdentityForgeIntake rejects intake settings on an identity; only +// the root forge's are read. func validateIdentityForgeIntake(identities []config.IdentityConfig) error { for i, id := range identities { switch id.Forge.Intake { @@ -296,11 +213,8 @@ func validateIdentityForgeIntake(identities []config.IdentityConfig) error { return nil } -// identitySettingPath renders the location of a per-identity setting, naming -// the identity as well as indexing it: an operator reading a rejection for a -// four-entry [[identities]] block finds the offender by its name instead of -// counting entries. The name is omitted when it is empty, because this runs -// before validateIdentities has required it. +// identitySettingPath renders a per-identity setting's location, with its +// name when set. func identitySettingPath(i int, id config.IdentityConfig, field string) string { if id.Name == "" { return fmt.Sprintf("identities[%d].%s", i, field) @@ -327,11 +241,8 @@ func validateProviders(providers map[string]config.Provider) error { return nil } -// validateIdentityStructure judges the shape of the identity definitions: the -// fields a process needs to know which identities exist and which credentials -// each one commits and calls with. The repository lists inside them are judged -// by validateRepositoryContents, because repositories are a control-plane -// resource that replaces the file's list after the merge. +// validateIdentityStructure checks identity definitions, excluding their +// repository lists. func validateIdentityStructure(cfg *config.Config) error { if len(cfg.Identities) == 0 { return validateSingleIdentity(cfg) @@ -363,12 +274,7 @@ func validateIdentities(identities []config.IdentityConfig) error { return nil } -// ForgeDisabled reports whether a forge type explicitly opts out of forge -// integration. It is the single definition shared by config validation and -// cmd/archied's resolveForge: adding or removing an alias here applies to -// both paths together. It is not consulted by forge.New, which has its own -// construction-time dispatch for disabled types (and the empty string); -// that dispatch is a different concern from this validation predicate. +// ForgeDisabled reports whether a forge type disables forge integration. func ForgeDisabled(t string) bool { return t == forgeTypeNone || t == forgeTypeOff || t == forgeTypeDisabled } @@ -386,12 +292,8 @@ func validateSingleIdentity(cfg *config.Config) error { return nil } -// validateRepositoryContents judges the repositories themselves, whichever list -// they appear in. The shared list is the decision the database's copy replaces, -// so it is verified on the effective document -- after that replacement, which is -// the only point the value being judged is the one a process will use. The -// per-identity lists are verified there for a different reason: no resource -// carries them, and the daemon is the only process that reads them +// validateRepositoryContents checks the shared and per-identity repository +// lists. func validateRepositoryContents(cfg *config.Config) error { if len(cfg.Identities) == 0 { return ValidateRepositories(cfg.Repos) @@ -404,14 +306,8 @@ func validateRepositoryContents(cfg *config.Config) error { return nil } -// ValidateRepositories judges a repository list: owner and name present, no -// duplicate entries, and a test glob the gate can compile. It is exported -// because the repository-policies resource validator (internal/app/controlplane) -// judges the same list -- that resource is seeded from these and replaces them -// wholesale, so the two layers must not disagree about which lists are valid, in -// either direction: a list one layer accepts and the other refuses is a config -// that boots file-side and stores nowhere, or a stored value the daemon then -// refuses to start with. +// ValidateRepositories checks a repository list: owner and name set, no +// duplicates, and a valid test glob. func ValidateRepositories(repos []config.Repo) error { seen := make(map[string]struct{}, len(repos)) for i, r := range repos { @@ -493,12 +389,7 @@ func validateContainers(cfg *config.Config) error { if err := cfg.Containers.ValidateCredentialBindings(); err != nil { return fmt.Errorf("%w: %w", ErrInvalidInput, err) } - // A registry credential that names only one half of the reference can only - // be a typo, and the pool cannot resolve it into the header a private - // registry needs -- the same rule resolveProviderMap applies to provider - // keys. The zero reference is deliberately accepted: anonymous pulls are - // the behaviour for a deployment with no private registry, and this field - // existing must not change that. + // A registry credential must set both engine and key, or neither. if ref := cfg.Containers.RegistryAuth; ref != (config.SecretRef{}) && (ref.Engine == "" || ref.Key == "") { return fmt.Errorf("%w: containers.registry_auth must name both an engine and a key, got {engine: %q, key: %q}", ErrInvalidInput, ref.Engine, ref.Key) } diff --git a/internal/tools/builtin/bridge.go b/internal/tools/builtin/bridge.go index 347f5927c..8deadae3f 100644 --- a/internal/tools/builtin/bridge.go +++ b/internal/tools/builtin/bridge.go @@ -1,12 +1,3 @@ -// Lifted from tau internal/agent/tools/bridge.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. package builtin import ( @@ -27,11 +18,7 @@ type UIBridge interface { Input(ctx context.Context, title, placeholder string) (string, error) Notify(title, level string) Log(chunk string) - // SessionID returns the session this bridge instance is scoped to for - // the current tool call, or "" when there is no session context (e.g. - // NonInteractiveBridge). Tools that need to correlate their own - // forwarded events to the calling session (e.g. the agent tool) read - // this instead of requiring it to be threaded through static config. + // SessionID returns the current tool call's session, or "". SessionID() string } diff --git a/internal/tools/builtin/builtin.go b/internal/tools/builtin/builtin.go index 303077b5d..a035767b2 100644 --- a/internal/tools/builtin/builtin.go +++ b/internal/tools/builtin/builtin.go @@ -1,17 +1,3 @@ -// Lifted from tau internal/agent/tools/builtin.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// - the docs tool is not registered and docs.go was not lifted. It serves -// tau's own embedded documentation via the tau/docs package, which has -// no meaning here. The pluginDocs parameter went with it. -// - the workspace codesearch index parameter was removed along with the -// index itself; RegisterBuiltins takes only the registry and cwd. -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. package builtin // RegisterBuiltins registers all built-in tools into the given registry. diff --git a/internal/tools/builtin/confinement.go b/internal/tools/builtin/confinement.go index be51a66d6..f9d89fc58 100644 --- a/internal/tools/builtin/confinement.go +++ b/internal/tools/builtin/confinement.go @@ -12,14 +12,8 @@ import ( // ErrPathNotAllowed reports a path refused by the workspace confinement. var ErrPathNotAllowed = errors.New("path is outside the configured workspace") -// ResolveReadable resolves path the way the read tool does -- relative -// against cwd, leading @ stripped -- and refuses anything the read tool -// would refuse, returning the absolute path when it is allowed. -// -// Callers that hand a file to somewhere outside the process (an outbound -// attachment, say) must gate on this rather than on their own check: the -// jail is a deployment posture, and a second implementation of it is a -// second thing to keep in step with SetPathConfinement. +// ResolveReadable resolves path as the read tool does and returns it when +// the read tool would allow it. func ResolveReadable(cwd, path string) (string, error) { resolved := resolvePath(cwd, path) if !isReadConfined(cwd, resolved) { diff --git a/internal/tools/builtin/edit.go b/internal/tools/builtin/edit.go index 81c890b96..9a5f00e99 100644 --- a/internal/tools/builtin/edit.go +++ b/internal/tools/builtin/edit.go @@ -1,12 +1,3 @@ -// Lifted from tau internal/agent/tools/edit.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. package builtin import ( @@ -236,13 +227,8 @@ type editSpan struct { editIdx int // index of the edit that produced this span (for errors) } -// applyEdits resolves every edit against the ORIGINAL content, validates that -// the resulting replacement spans do not overlap, and applies them in one -// pass. It never partially applies: any error leaves the content untouched. -// -// Matching is exact first; if old_text is not found, a fuzzy pass retries the -// match with trailing whitespace stripped from every line of both the content -// and old_text, which recovers the most common exact-match failure. +// applyEdits applies every edit against the original content in one pass, +// or none on any error. Overlapping edits are an error. func applyEdits(content string, edits []EditAction) (string, error) { var spans []editSpan @@ -268,11 +254,8 @@ func applyEdits(content string, edits []EditAction) (string, error) { return renderSpans(content, spans), nil } -// resolveEditSpans resolves one edit against the original content into the -// span(s) it applies. Matching is exact first; if old_text is not found, a -// fuzzy pass retries the match with trailing whitespace stripped from every -// line of both the content and old_text, which recovers the most common -// exact-match failure. +// resolveEditSpans finds an edit's spans: exact match first, then ignoring +// trailing whitespace. func resolveEditSpans(content string, edit EditAction, i int) ([]editSpan, error) { matches := indexAll(content, edit.OldText) @@ -345,16 +328,8 @@ func editNotFoundError(idx int, content, oldText string) error { return errors.New(base) } -// nearestMatchHint locates the most likely intended location for a failed -// old_text and quotes the file's actual text there, so the model can correct -// the edit from the error alone instead of spending a round trip re-reading -// the file. stale_edit was 6.7% of all edit calls across analysed sessions. -// -// The anchor is the first non-blank line of old_text compared with leading and -// trailing whitespace removed, because indentation drift is the dominant cause: -// the model reproduces the right code at the wrong nesting depth. Matching on -// content alone is deliberately loose - a wrong hint costs nothing beyond a few -// lines of output, whereas no hint costs a whole round trip. +// nearestMatchHint quotes the file's text where a failed old_text most likely +// belongs, matched on its first non-blank line ignoring indentation. func nearestMatchHint(content, oldText string) string { var anchor string wantLines := strings.Split(oldText, "\n") diff --git a/internal/tools/builtin/find.go b/internal/tools/builtin/find.go index 2c96cfdbf..637d0b16f 100644 --- a/internal/tools/builtin/find.go +++ b/internal/tools/builtin/find.go @@ -1,16 +1,3 @@ -// Lifted from tau internal/agent/tools/find.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// - discovery is confined to the active workspace. Module-cache and other -// absolute paths are rejected so find cannot list home or pkg/mod trees. -// - runFindGoFallback split into compileFindFilter and findWalkVisitor to -// satisfy golangci-lint's gocognit limit. No behavioural change. -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. package builtin import ( diff --git a/internal/tools/builtin/fsutil.go b/internal/tools/builtin/fsutil.go index df7bdd56a..86d1a7eee 100644 --- a/internal/tools/builtin/fsutil.go +++ b/internal/tools/builtin/fsutil.go @@ -1,12 +1,3 @@ -// Lifted from tau internal/agent/tools/fsutil.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. package builtin import ( @@ -15,15 +6,9 @@ import ( "path/filepath" ) -// runWithContext runs fn in a goroutine and returns its result, or ctx.Err() -// if ctx is done first. Go cannot forcibly cancel a blocked syscall (e.g. a -// hung NFS/FUSE mount), so fn's goroutine is not killed - it keeps running -// in the background and its result is discarded - but the caller stops -// waiting on it, so a hung filesystem can no longer block the tool executor -// (and therefore the coordinator's turn loop) indefinitely. -// -// If the context is already done when runWithContext is called, fn is never -// spawned. This avoids a goroutine leak that can race with test cleanup. +// runWithContext runs fn and returns its result, or ctx.Err() if ctx ends +// first; fn keeps running in the background. fn is not started if ctx is +// already done. func runWithContext(ctx context.Context, fn func() error) error { if err := ctx.Err(); err != nil { return err diff --git a/internal/tools/builtin/grep.go b/internal/tools/builtin/grep.go index aa449ea73..42af846de 100644 --- a/internal/tools/builtin/grep.go +++ b/internal/tools/builtin/grep.go @@ -1,26 +1,3 @@ -// Lifted from tau internal/agent/tools/grep.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// - the embedded ripgrep binaries (upstream internal/tools/builtin/rg) were -// removed. They were 14MB of tracked binaries that were re-extracted to a -// temporary directory on every run. grepBinary now resolves rg from PATH -// and the existing pure-Go grepFallback covers its absence. -// - discovery is confined to the active workspace. Module-cache and other -// absolute paths are rejected so grep cannot search home or pkg/mod trees. -// - makeGrepExecutor, grepFallback, and grepDirFallback were split into -// smaller helpers (resolveGrepTargets, runGrepBinary, grepExplicitTargets, -// setGrepResultsRelPath, grepWalkVisitor) to satisfy golangci-lint -// cyclop/gocognit limits. No behavioural change. -// - the workspace codesearch index integration was removed: GrepIndex, the -// candidate-narrowing path, the codesearch backend retry, and the -// search_backend metric are gone, and grep always walks the requested -// path directly. -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. package builtin import ( @@ -47,11 +24,7 @@ const ( grepDefaultLimit = 100 grepMaxBytes = 24 * 1024 - // grepMaxContext bounds context_before/context_after. Large context values - // spend the whole byte budget on padding: at the default limit of 100 - // matches, every extra context line is 100 extra lines of output, so a - // request for 10 lines either side truncates long before it has shown 100 - // distinct matches. Clamping keeps the budget on matches instead. + // grepMaxContext bounds context_before and context_after. grepMaxContext = 5 ) @@ -198,11 +171,7 @@ func runGrepBinary( err := cmd.Run() output := stdout.String() if output == "" && err != nil { - // Exit 1 means "no matches"; exit 2 means a real failure (bad - // pattern, unreadable path). Reporting the latter as an empty - // result would have the model state a file contains nothing when - // the search never ran, so the code must be checked, not just the - // error type. + // Exit 1 is no matches; exit 2 is a failure. var exitErr *exec.ExitError if errors.As(err, &exitErr) && exitErr.ExitCode() == 1 { return Result{Content: "no matches found"} @@ -530,13 +499,7 @@ func buildGrepArgs(p GrepParams) []string { return args } -// grepBinary resolves ripgrep from PATH. When it is absent the caller falls -// back to grepFallback, the pure-Go search, so this returning an error is an -// ordinary outcome rather than a failure. -// -// Upstream tau embeds ripgrep binaries for each platform and extracts one to -// a temporary directory on demand. That cost 14MB of tracked binaries and -// wrote the binary out again on every run, which is why it was removed here. +// grepBinary finds rg on PATH. Without it the caller uses grepFallback. func grepBinary() (string, error) { return exec.LookPath("rg") } diff --git a/internal/tools/builtin/mutation.go b/internal/tools/builtin/mutation.go index d401b6320..d31d49d89 100644 --- a/internal/tools/builtin/mutation.go +++ b/internal/tools/builtin/mutation.go @@ -1,26 +1,11 @@ -// Lifted from tau internal/agent/tools/mutation.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. package builtin import ( "sync" ) -// MutationQueue serializes write operations to the same file path, -// preventing concurrent edits from clobbering each other during -// parallel tool execution. -// -// A sync.RWMutex coordinates between shell commands and file-mutation -// tools. File mutations (write, edit) take a read lock so they -// can run concurrently with each other. Shell commands take the write -// lock, blocking all file mutations for the duration of the command. +// MutationQueue serializes writes per file path. File mutations share a read +// lock; shell commands take the write lock. type MutationQueue struct { mu sync.Mutex locks map[string]*mutexEntry @@ -55,17 +40,8 @@ func (q *MutationQueue) GlobalUnlock() { q.globalMu.Unlock() } -// Acquire returns a lock for the given file path. The caller must call -// the returned release function when done with the mutation. -// -// Acquire blocks while the global write lock is held (i.e. while a shell -// command is running). -// -// Usage: -// -// release := q.Acquire("/path/to/file.go") -// defer release() -// // ... perform read-modify-write ... +// Acquire locks path and returns the release function. It blocks while a +// shell command runs. func (q *MutationQueue) Acquire(path string) (release func()) { // Take a read lock so shell commands (which take the write lock) // block until we're done, and we block while a shell command runs. diff --git a/internal/tools/builtin/pathutil.go b/internal/tools/builtin/pathutil.go index f3ecf9a22..c89ec8e76 100644 --- a/internal/tools/builtin/pathutil.go +++ b/internal/tools/builtin/pathutil.go @@ -1,19 +1,3 @@ -// Lifted from tau internal/agent/tools/pathutil.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// - path confinement is switchable (SetPathConfinement). tau's agent is a -// coding assistant scoped to one project, where a workspace jail is always -// right. archie's chat agent is also used as a general-purpose operator -- -// partitioning a disk and mounting it, migrating data between filesystems, -// editing unit files -- and a jail makes that impossible. The shell tool -// was never confined anyway, so the jail only ever shaped which tool got -// used, not what the agent could reach. -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. package builtin import ( @@ -42,11 +26,7 @@ func resolvePath(cwd, path string) string { return filepath.Clean(filepath.Join(cwd, path)) } -// goModCacheDir returns the Go module cache root, or "" if it cannot be -// determined. It mirrors cmd/go's own resolution order rather than shelling -// out to `go env GOMODCACHE`, so path checks stay allocation-cheap and do not -// depend on a Go toolchain being installed. It is a var so tests can point it -// at a temp dir instead of the host's real cache. +// goModCacheDir returns the Go module cache root, or "". var goModCacheDir = sync.OnceValue(func() string { if v := os.Getenv("GOMODCACHE"); v != "" { return filepath.Clean(v) @@ -64,11 +44,8 @@ var goModCacheDir = sync.OnceValue(func() string { return filepath.Join(home, "go", "pkg", "mod") }) -// isReadConfined reports whether an explicit read may touch target. It permits -// the workspace plus the Go module cache so a known dependency file can be -// opened by path. Discovery tools (find, grep) use isConfined instead and stay -// inside the active project/worktree. The cache is deliberately NOT extended -// to the mutating tools (edit, write). +// isReadConfined reports whether a read may touch target: the workspace or +// the Go module cache. func isReadConfined(base, target string) bool { if isConfined(base, target) { return true @@ -77,33 +54,14 @@ func isReadConfined(base, target string) bool { return cache != "" && isConfined(cache, target) } -// pathConfinement gates the workspace jail on the file tools. It defaults to -// on; see SetPathConfinement. -// -// Process-wide rather than per-tool because it is a deployment posture, not a -// property of one tool: a daemon either trusts its agent with the filesystem or -// it does not, and there is one builtin tool set per process. +// pathConfinement gates the workspace jail on the file tools. On by default. var pathConfinement atomic.Bool func init() { pathConfinement.Store(true) } // SetPathConfinement turns the workspace jail on the read, write, edit, find -// and grep tools on or off. It is set once at startup from configuration. -// -// Disabling it makes those tools reach any absolute path. That is the point: -// an agent asked to partition a new disk, mount it and migrate data onto it is -// working across the filesystem by definition, and a jail turns a capable -// operator into a useless one. -// -// It widens which TOOL can do the work, not what the agent can reach. The shell -// tool has never been confined -- it can cd anywhere, and only command.Hardline -// screens it -- so a jailed deployment simply pushed the agent into doing -// everything through shell, losing the truncation, line numbering, -// read-before-write tracking and structured errors the dedicated tools provide. -// -// Relative paths still resolve against the workspace either way (see -// resolvePath), so turning this off does not silently move where an existing -// relative path lands. +// and grep tools on or off. Relative paths always resolve against the +// workspace. func SetPathConfinement(enabled bool) { pathConfinement.Store(enabled) } // isConfined checks whether target is within (or equal to) the base directory. diff --git a/internal/tools/builtin/procgroup_unix.go b/internal/tools/builtin/procgroup_unix.go index f51da6f1d..54e2ec390 100644 --- a/internal/tools/builtin/procgroup_unix.go +++ b/internal/tools/builtin/procgroup_unix.go @@ -1,12 +1,3 @@ -// Lifted from tau internal/agent/tools/procgroup_unix.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. //go:build !windows package builtin diff --git a/internal/tools/builtin/procgroup_windows.go b/internal/tools/builtin/procgroup_windows.go index 6a83c80b6..b00082920 100644 --- a/internal/tools/builtin/procgroup_windows.go +++ b/internal/tools/builtin/procgroup_windows.go @@ -1,12 +1,3 @@ -// Lifted from tau internal/agent/tools/procgroup_windows.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. //go:build windows package builtin @@ -26,12 +17,8 @@ func setProcessGroup(cmd *exec.Cmd) { cmd.SysProcAttr.CreationFlags |= syscall.CREATE_NEW_PROCESS_GROUP } -// signalProcessGroup best-effort terminates cmd's direct process on -// Windows. Windows has no POSIX-style negative-pid group signal; the spec's -// documented fallback is TerminateProcess (GenerateConsoleCtrlEvent would -// require additional job-object/console plumbing this doesn't set up), so -// descendants spawned by the child are not guaranteed to receive this - -// a known platform limitation, not an oversight. +// signalProcessGroup terminates cmd's process on Windows; descendants may +// survive. func signalProcessGroup(cmd *exec.Cmd, _ syscall.Signal) error { if cmd.Process == nil { return nil diff --git a/internal/tools/builtin/read.go b/internal/tools/builtin/read.go index 064b42c32..4a06642da 100644 --- a/internal/tools/builtin/read.go +++ b/internal/tools/builtin/read.go @@ -1,15 +1,3 @@ -// Lifted from tau internal/agent/tools/read.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// - serveReadContent split into readOffsetLimitWindow and -// readTrailingNotice to satisfy golangci-lint's cyclop limit. No -// behavioural change. -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. package builtin import ( @@ -40,11 +28,7 @@ const DefaultReadLines = 400 var readSchema = Schema{ Name: "read", Description: fmt.Sprintf("Read file contents; pointed at a directory it returns a listing. Omitted limits return at most %d lines; set full:true only when the complete file is genuinely needed. Output is always capped at %d lines or %s and includes a continuation offset.", DefaultReadLines, DefaultMaxLines, FormatSize(DefaultMaxBytes)), - // NOTE: file is a compatibility alias for path; the executor - // handles the fallback (file → path) and returns a clear error - // when both are empty. We intentionally do NOT use anyOf here - // because the OpenAI Responses API rejects schemas with - // anyOf/oneOf/allOf at the top level of the parameters object. + // file is an alias for path. No anyOf: the OpenAI Responses API rejects it. Parameters: json.RawMessage(`{ "type": "object", "properties": { @@ -81,12 +65,7 @@ const ( maxSuggestionScan = 20000 ) -// suggestPaths looks for files sharing the missing path's basename. Reads that -// fail on a plausible-but-wrong path cost a round trip plus a follow-up find; -// naming the real location lets the model correct itself immediately. -// -// The match is on basename alone, which is loose, but a wrong suggestion costs -// one line of output while no suggestion costs a whole round trip. +// suggestPaths lists files sharing the missing path's basename. func suggestPaths(cwd, missing string) string { if cwd == "" { return "" @@ -363,11 +342,7 @@ func serveReadContent(cwd, path string, p readParams, info os.FileInfo, state *r return Result{Content: fmt.Sprintf("offset %d exceeds file length (%d lines)", startLine, totalLines), IsError: true} } - // Skip lines this session has already been shown from an unchanged - // file. Repeated reads were 23.6% of all tool result tokens across - // analysed sessions - one file was read 58 times in a single session. - // full:true is the deliberate escape hatch for a model that has lost - // the earlier content (compaction, handoff) and needs it resent. + // Skip lines already shown from an unchanged file unless full is set. requestedStart := startLine if rt != nil && !p.Full { novelStart, novelEnd, hasNovel := rt.Novel(cwd, p.Path, FileIdentity(info), startLine, endLine) @@ -411,11 +386,7 @@ func readOffsetLimitWindow(p readParams, totalLines int) (startLine, endLine int return startLine, endLine } -// readTrailingNotice returns the suffix appended to the served content: a -// shell-fallback hint when the first requested line alone exceeded the byte -// limit, a continuation hint when the byte limit truncated mid-range, or a -// continuation hint when a user-specified limit stopped before EOF. Returns -// "" when none apply. +// readTrailingNotice returns the hint appended after served content, or "". func readTrailingNotice(p readParams, tr TruncationResult, lines []string, startLine, endLine, totalLines int) string { switch { case tr.Truncated && tr.OutputLines == 0: diff --git a/internal/tools/builtin/read_outline.go b/internal/tools/builtin/read_outline.go index 93d67aecc..010fc5923 100644 --- a/internal/tools/builtin/read_outline.go +++ b/internal/tools/builtin/read_outline.go @@ -1,12 +1,3 @@ -// Lifted from tau internal/agent/tools/read_outline.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. package builtin import ( @@ -44,15 +35,8 @@ func tsOutlineRe() *regexp.Regexp { return regexp.MustCompile(`^(export\s|async\s+function\s|function\s|class\s|interface\s|type\s|const\s|enum\s)`) } -// outlineFor renders a line-numbered index of a large source file's top-level -// declarations, or "" when an outline is not appropriate. -// -// 15 reads in the analysed corpus landed in the 4k-16k token buckets, roughly -// 18% of all read tokens. DefaultReadLines bounds the line count but not the -// value: the first 400 lines of a 1,500-line file are mostly imports and -// whichever declarations happen to sort first, which is rarely what the model -// was looking for. An index of the whole file plus a targeted follow-up read is -// both cheaper and more likely to land on the right code. +// outlineFor returns a line-numbered index of a large source file's +// top-level declarations, or "". func outlineFor(path string, lines []string) string { pattern, ok := outlinePatterns[strings.ToLower(filepath.Ext(path))] if !ok { diff --git a/internal/tools/builtin/read_tracker.go b/internal/tools/builtin/read_tracker.go index 245e2106b..2fa312636 100644 --- a/internal/tools/builtin/read_tracker.go +++ b/internal/tools/builtin/read_tracker.go @@ -1,12 +1,3 @@ -// Lifted from tau internal/agent/tools/read_tracker.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. package builtin import ( @@ -46,23 +37,14 @@ func NewReadTracker() *ReadTracker { } } -// FileIdentity is a cheap fingerprint of a file's current state. Size plus -// modification time is enough here: a rewrite that preserves both is -// indistinguishable from no change, and the cost of being wrong is a stale -// suppression notice the model can override with full:true. Hashing every -// re-read would be strictly more accurate and materially more expensive. +// FileIdentity fingerprints a file by size and modification time. func FileIdentity(info os.FileInfo) string { return fmt.Sprintf("%d:%d", info.Size(), info.ModTime().UnixNano()) } -// Novel reports which part of [start,end] the model has not already been shown -// for this file, and records the whole request as served. -// -// It returns ok=false when the request is entirely covered, meaning read should -// suppress the body. When only part is new AND that part is contiguous, the -// narrowed range is returned. A request whose novel portion is fragmented is -// served whole, because stitching disjoint fragments into one response is more -// confusing to the model than simply repeating some lines. +// Novel returns the part of [start,end] not yet shown for this file and +// records the request. ok is false when all of it was shown. A fragmented +// remainder is served whole. func (rt *ReadTracker) Novel(cwd, path, identity string, start, end int) (ns, ne int, ok bool) { abs := resolvePath(cwd, path) diff --git a/internal/tools/builtin/registry.go b/internal/tools/builtin/registry.go index c860c67c7..0b1c5eb90 100644 --- a/internal/tools/builtin/registry.go +++ b/internal/tools/builtin/registry.go @@ -1,14 +1,4 @@ -// Lifted from tau internal/agent/tools/registry.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. -// Package tools provides the tool registry and built-in tool implementations -// for the Tau agent coordinator. +// Package builtin provides the agent's built-in file and shell tools. package builtin import ( diff --git a/internal/tools/builtin/shell.go b/internal/tools/builtin/shell.go index d53a740e8..41d83006a 100644 --- a/internal/tools/builtin/shell.go +++ b/internal/tools/builtin/shell.go @@ -1,22 +1,3 @@ -// Lifted from tau internal/agent/tools/shell.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// - the command runs in its own process group and cancellation signals -// the whole group. Upstream relies on exec.CommandContext's default, -// which kills only the direct shell, so `go test ./...` left its test -// binary running and `nohup x &` survived outright. archie's /stop -// cancels the turn context, so without this the command it was aimed -// at would keep going. tau applies the same treatment to spawned -// agents in agent.go; this extends it to the shell tool. -// - makeShellExecutor split into buildShellCmd, formatShellOutput, and -// shellErrorResult to satisfy golangci-lint's gocognit limit. No -// behavioural change. -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. package builtin import ( @@ -221,11 +202,7 @@ func shellErrorResult(ctx context.Context, err error, timeout time.Duration, con return Result{Content: fmt.Sprintf("error executing command: %v", err), IsError: true} } -// goTestSummaryRe matches cmd/go's per-package result lines: "ok", "FAIL" and -// "?" (no test files). Note it must NOT match "---", which prefixes per-test -// result lines ("--- PASS: TestX") - exactly the noise being collapsed. A -// package that fails to build reports as "FAIL [build failed]", so the -// package-level failure case is already covered by the FAIL alternative. +// goTestSummaryRe matches go test's per-package result lines. var goTestSummaryRe = regexp.MustCompile(`^(ok|FAIL|\?)\s`) // goTestInvocationRe matches a `go test` invocation, allowing for a leading @@ -233,14 +210,8 @@ var goTestSummaryRe = regexp.MustCompile(`^(ok|FAIL|\?)\s`) // match wrappers like gotestsum, whose output format differs. var goTestInvocationRe = regexp.MustCompile(`(^|[;&|]\s*)go\s+test\b`) -// collapseGoTestOutput reduces a PASSING `go test` run to its per-package -// summary lines. A single `go test ./internal/tui2/... -v` in the analysed -// sessions took 14.2s and returned 11,044 tokens - 11% of all shell result -// tokens in one call - despite every test having passed, where the only -// information the model needed was "they passed". -// -// Failing runs are returned verbatim: on failure the per-test detail is the -// entire point, and collapsing it would force a re-run to recover it. +// collapseGoTestOutput reduces a passing go test run to its per-package +// summary lines. Failing output is unchanged. func collapseGoTestOutput(command, output string, succeeded bool) (string, bool) { if !succeeded || !goTestInvocationRe.MatchString(command) { return output, false diff --git a/internal/tools/builtin/truncate.go b/internal/tools/builtin/truncate.go index d69f1b66b..2736f31be 100644 --- a/internal/tools/builtin/truncate.go +++ b/internal/tools/builtin/truncate.go @@ -1,12 +1,3 @@ -// Lifted from tau internal/agent/tools/truncate.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. package builtin import ( diff --git a/internal/tools/builtin/write.go b/internal/tools/builtin/write.go index 0bd7c76a4..65c4f4b5d 100644 --- a/internal/tools/builtin/write.go +++ b/internal/tools/builtin/write.go @@ -1,12 +1,3 @@ -// Lifted from tau internal/agent/tools/write.go -// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d. -// -// Mutations from upstream: -// - package renamed tools -> builtin (archie-core already has an -// internal/tools package holding the registry these are registered into). -// -// Refresh by diffing against that path at a newer tau commit. Do not -// edit without recording the change above. package builtin import ( @@ -128,11 +119,9 @@ func isRegularFile(path string) bool { return err == nil && info.Mode().IsRegular() } -// checkExistingFile returns the prior content of an existing regular file and, -// when a write should not proceed, a blocking error result. It enforces the -// read-before-write rule and overwrite opt-in, returning nil when the file may -// be written. Non-regular or missing paths return an empty content and no -// block. +// checkExistingFile returns an existing file's content and, when the write +// must not proceed, an error result. It enforces read-before-write and +// overwrite opt-in. func checkExistingFile(path, cwd, relPath string, overwrite bool, rt *ReadTracker) (string, *Result) { if !isRegularFile(path) { return "", nil