refactor(configuration,builtin): cut comments down to what the code does

This commit is contained in:
sam committed 2026-10-03 21:58:23 +10:00
1 parent fc8ce7e84b
commit 02537366eb
29 files changed
+128 -809

No files matched your search

+8 -43
View File
@@ -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() {
@@ -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 {
@@ -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 {
@@ -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",
@@ -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
+3 -32
View File
@@ -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
@@ -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
+18 -73
View File
@@ -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.<name>] 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.<name>] 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)
@@ -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
}
+3 -17
View File
@@ -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 {
+26 -135
View File
@@ -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)
}
+1 -14
View File
@@ -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
}
-14
View File
@@ -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.
+2 -8
View File
@@ -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) {
+6 -31
View File
@@ -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")
-13
View File
@@ -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 (
+3 -18
View File
@@ -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
+3 -40
View File
@@ -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")
}
+4 -28
View File
@@ -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.
+6 -48
View File
@@ -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.
-9
View File
@@ -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
+2 -15
View File
@@ -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
+4 -33
View File
@@ -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:
+2 -18
View File
@@ -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 {
+4 -22
View File
@@ -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)
+1 -11
View File
@@ -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 (
+3 -32
View File
@@ -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 <pkg> [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
-9
View File
@@ -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 (
+3 -14
View File
@@ -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