feat(agent): seed a starter SOUL and upgrade only untouched templates

This commit is contained in:
sam committed 2026-10-02 11:06:40 +10:00
1 parent 1f0cb9f318
commit cc83c9aea2
7 files changed
+640

No files matched your search

+21
View File
@@ -32,6 +32,7 @@ import (
controlpb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1"
"github.com/samcharles93/archie-core/internal/daemon"
"github.com/samcharles93/archie-core/internal/domain/access"
"github.com/samcharles93/archie-core/internal/domain/agent"
"github.com/samcharles93/archie-core/internal/domain/applystatus"
"github.com/samcharles93/archie-core/internal/domain/curator"
"github.com/samcharles93/archie-core/internal/domain/eda/module"
@@ -593,6 +594,26 @@ func (b *boot) loadCatalog(ctx context.Context, cfgPath string) {
b.log.Info("model catalog loaded", "providers", len(catalog.Providers), "models", len(models))
}
// seedSoul writes the starter SOUL beside the config on first run, and upgrades
// a file that is still exactly a shipped template, so the identity a user can
// edit exists before the SOUL loader (#439) reads it. It runs on the full
// process's boot tail rather than in loadConfig: an offline command such as
// `-requeue` reads the config but must not write the operator's files. A
// failure is logged, not fatal -- the loader falls back to the embedded
// default, so a read-only config directory must not stop the process
// (docs/prds/soul.md, "Prompt and failure contract").
func (b *boot) seedSoul(cfgPath string) {
result, err := configuration.SeedSoul(cfgPath, agent.ShippedSoul())
if err != nil {
b.log.Warn("soul: starter file unavailable", "err", err)
return
}
switch result.Action {
case configuration.SoulCreated, configuration.SoulUpgraded:
b.log.Info("soul: starter file written", "path", result.Path, "action", result.Action)
}
}
// refreshModelCatalog re-reads the catalog and republishes everything derived
// from it, so a credential that becomes resolvable after boot or a model added
// upstream reaches the running config, the dashboard and the chat runtime
+1
View File
@@ -72,6 +72,7 @@ func RunGateway(ctx context.Context, options GatewayOptions) error {
return err
}
b.loadCatalog(ctx, options.Config)
b.seedSoul(options.Config)
url, token := b.cfg.NATS.URL, ""
var nc *natsio.Conn
var err error
+1
View File
@@ -381,6 +381,7 @@ func Run() int { //nolint:cyclop,funlen // the composition root's setup sequence
return 0
}
b.loadCatalog(ctx, args.cfgPath)
b.seedSoul(args.cfgPath)
b.setupObservability(ctx)
if err := b.setupBackends(ctx); err != nil {
+93
View File
@@ -0,0 +1,93 @@
package agent
import "strings"
// DefaultSoul is the starter SOUL document this build ships.
//
// It is deliberately independent of ShippedPersonas: the persona catalogue is
// a style axis that is being retired, while the starter SOUL is the fallback
// identity a user edits. Deleting personas must not delete the fallback.
//
// The document is plain Markdown and becomes the identity slot of the system
// prompt, XML-escaped beneath the invariant sections. It owns the agent's
// name, register and warmth only; it cannot change the rules, tools or runtime
// metadata, so keep it to identity prose.
const DefaultSoul = `# Archie
You are Archie, a capable coding and project assistant. Be direct without being
brusque, grounded in the actual workspace state, and use available tools when
asked. Do not claim tools, files, memories, actions, or results you have not
verified. Do not impersonate another assistant, provider, or vendor.
`
// SoulMatch classifies a SOUL body against the documents a build ships.
type SoulMatch int
const (
// SoulEdit is content no build shipped: a user edit, which must never be
// replaced.
SoulEdit SoulMatch = iota
// SoulCurrent is content identical to the build's Default once transport
// noise is normalised away; there is nothing to upgrade.
SoulCurrent
// SoulSuperseded is a body this build recognises as a shipped template
// that is not the current Default. It carries zero user intent, so it may
// be upgraded in place.
SoulSuperseded
)
// SoulDocument is the set of SOUL bodies one build recognises as its own.
type SoulDocument struct {
// Default is written when no SOUL file exists, and replaces a superseded
// template during an upgrade.
Default string
// Legacy lists earlier shipped SOUL bodies this build still recognises. A
// file that matches one is an untouched scaffolding document rather than a
// user edit. The Default is always recognised and need not be repeated.
Legacy []string
}
// ShippedSoul returns the SOUL document this build ships.
func ShippedSoul() SoulDocument {
return SoulDocument{Default: DefaultSoul}
}
// Match classifies a body against the build's shipped documents.
//
// Comparison is on normalised content, so a CRLF checkout or an editor that
// left trailing whitespace still matches the template it came from. Only a
// body that is identical to a shipped document after that normalisation is
// eligible for replacement; any other difference is treated as user intent.
func (d SoulDocument) Match(content string) SoulMatch {
if d.Default == "" {
return SoulEdit
}
normalized := normalizeSoul(content)
if normalized == normalizeSoul(d.Default) {
return SoulCurrent
}
for _, legacy := range d.Legacy {
if legacy == "" {
continue
}
if normalized == normalizeSoul(legacy) {
return SoulSuperseded
}
}
return SoulEdit
}
// normalizeSoul reduces a SOUL body to the content a user authored: a UTF-8
// BOM is dropped, CRLF and lone CR become LF, and trailing whitespace is
// removed from every line and from the end of the document. None of that
// carries intent, so it must not make an untouched template look edited.
func normalizeSoul(content string) string {
content = strings.TrimPrefix(content, "\ufeff")
content = strings.ReplaceAll(content, "\r\n", "\n")
content = strings.ReplaceAll(content, "\r", "\n")
lines := strings.Split(content, "\n")
for index, line := range lines {
lines[index] = strings.TrimRight(line, " \t")
}
return strings.TrimRight(strings.Join(lines, "\n"), "\n")
}
+73
View File
@@ -0,0 +1,73 @@
package agent
import "testing"
func TestShippedSoulShipsAStarter(t *testing.T) {
t.Parallel()
shipped := ShippedSoul()
if shipped.Default == "" {
t.Fatal("ShippedSoul().Default is empty; first run would seed nothing")
}
if got := shipped.Match(shipped.Default); got != SoulCurrent {
t.Fatalf("Match(shipped default) = %v, want SoulCurrent", got)
}
}
func TestShippedSoulIsIndependentOfPersonas(t *testing.T) {
t.Parallel()
// The fallback identity has a single owner. If a persona prompt were the
// starter, retiring the persona catalogue (its own bead) would delete the
// fallback with it.
for _, persona := range ShippedPersonas().Personas {
if persona.Prompt == DefaultSoul {
t.Fatalf("DefaultSoul is the %q persona prompt; it must be shipped independently", persona.Name)
}
}
}
func TestSoulMatch(t *testing.T) {
t.Parallel()
const legacy = "# Archie\n\nOld starter identity.\n"
doc := SoulDocument{Default: "current\nidentity\n", Legacy: []string{legacy}}
tests := []struct {
name string
content string
want SoulMatch
}{
{name: "exact default", content: doc.Default, want: SoulCurrent},
{name: "default with crlf", content: "current\r\nidentity\r\n", want: SoulCurrent},
{name: "default with lone cr", content: "current\ridentity\r", want: SoulCurrent},
{name: "default with trailing spaces", content: "current \nidentity\t\n", want: SoulCurrent},
{name: "default with trailing blank lines", content: "current\nidentity\n\n\n", want: SoulCurrent},
{name: "default with utf8 bom", content: "\ufeffcurrent\nidentity\n", want: SoulCurrent},
{name: "legacy template", content: legacy, want: SoulSuperseded},
{name: "legacy template with crlf", content: "# Archie\r\n\r\nOld starter identity.\r\n", want: SoulSuperseded},
{name: "legacy template with trailing whitespace", content: "# Archie\n\nOld starter identity. \n", want: SoulSuperseded},
{name: "an edited word", content: "current\nIDENTITY\n", want: SoulEdit},
{name: "leading indent is content", content: "current\n identity\n", want: SoulEdit},
{name: "one word removed", content: "current\n", want: SoulEdit},
{name: "empty", content: "", want: SoulEdit},
{name: "whitespace only", content: "\n\t \n", want: SoulEdit},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
t.Parallel()
if got := doc.Match(test.content); got != test.want {
t.Fatalf("Match(%q) = %v, want %v", test.content, got, test.want)
}
})
}
}
func TestSoulMatchTreatsMissingDefaultAsEdited(t *testing.T) {
t.Parallel()
var doc SoulDocument
if got := doc.Match("anything"); got != SoulEdit {
t.Fatalf("empty document Match = %v, want SoulEdit", got)
}
}
@@ -0,0 +1,185 @@
package configuration
import (
"errors"
"fmt"
"io/fs"
"os"
"path/filepath"
"github.com/samcharles93/archie-core/internal/domain/agent"
)
// SoulFilename is the SOUL document's file name in the configuration
// directory. The root agent owns it directly; per-agent directories are a
// later concern and are not invented here.
const SoulFilename = "SOUL.md"
// maxSoulReadBytes bounds how much of an existing SOUL file the upgrade check
// reads. A SOUL is at most 8 KiB once validated, so a larger file cannot be a
// shipped template and is treated as a user edit without reading it in full.
const maxSoulReadBytes = 64 << 10
// SoulSeedAction is what SeedSoul did to a SOUL file.
type SoulSeedAction string
const (
// SoulCreated wrote the starter because no file existed.
SoulCreated SoulSeedAction = "created"
// SoulUpgraded replaced a file that was still exactly a shipped template.
SoulUpgraded SoulSeedAction = "upgraded"
// SoulCurrent found the build's current document already in place.
SoulCurrent SoulSeedAction = "current"
// SoulPreserved left a user edit (or an unreadable/oversized file) alone.
SoulPreserved SoulSeedAction = "preserved"
)
// SoulSeedResult records the file SeedSoul acted on and what it did, so boot
// can log the decision without re-reading the file.
type SoulSeedResult struct {
Path string
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.
func ConfigDir(configPath string) string {
if info, err := os.Stat(configPath); err == nil && info.IsDir() {
return configPath
}
return filepath.Dir(configPath)
}
// SoulPath returns the SOUL file path for a selected config path.
func SoulPath(configPath string) string {
return filepath.Join(ConfigDir(configPath), SoulFilename)
}
// SeedSoul writes the starter SOUL into the configuration directory when no
// file exists, upgrades a file whose content is still exactly a shipped
// template, and leaves anything else 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 every shipped
// template in any way 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.
func SeedSoul(configPath string, doc agent.SoulDocument) (SoulSeedResult, error) {
dir := ConfigDir(configPath)
if err := os.MkdirAll(dir, 0o700); err != nil {
return SoulSeedResult{}, fmt.Errorf("soul: create config dir %s: %w", dir, err)
}
return seedSoulFile(filepath.Join(dir, SoulFilename), doc)
}
// seedSoulFile applies the seed/upgrade/preserve decision to one path.
func seedSoulFile(path string, doc agent.SoulDocument) (SoulSeedResult, error) {
info, err := os.Lstat(path)
switch {
case errors.Is(err, fs.ErrNotExist):
if err := createSoulExclusive(path, doc.Default); err != nil {
if !errors.Is(err, fs.ErrExist) {
return SoulSeedResult{Path: path}, err
}
// Another process (the daemon and the standalone Gateway can both
// seed) created the file between the check and the create. Classify
// what is now there rather than reporting a failure for a file that
// is in fact present.
info, err = os.Lstat(path)
if err != nil {
return SoulSeedResult{Path: path}, fmt.Errorf("soul: stat %s: %w", path, err)
}
} else {
return SoulSeedResult{Path: path, Action: SoulCreated}, nil
}
case err != nil:
return SoulSeedResult{Path: path}, fmt.Errorf("soul: stat %s: %w", path, err)
}
return classifyExistingSoul(path, info, doc)
}
// classifyExistingSoul decides what to do with a SOUL file that is already on
// disk: leave the build's current document, upgrade an untouched shipped
// template, and preserve everything else.
func classifyExistingSoul(path string, info fs.FileInfo, doc agent.SoulDocument) (SoulSeedResult, error) {
// A symlink or any other non-regular file was not created by this seeder.
// Replacing it (an upgrade writes by rename) would destroy a user-managed
// indirection, so it is preserved.
if !info.Mode().IsRegular() {
return SoulSeedResult{Path: path, Action: SoulPreserved}, nil
}
if info.Size() > maxSoulReadBytes {
return SoulSeedResult{Path: path, Action: SoulPreserved}, nil
}
content, err := os.ReadFile(path)
if err != nil {
return SoulSeedResult{Path: path}, fmt.Errorf("soul: read %s: %w", path, err)
}
switch doc.Match(string(content)) {
case agent.SoulCurrent:
return SoulSeedResult{Path: path, Action: SoulCurrent}, nil
case agent.SoulSuperseded:
if err := replaceSoul(path, doc.Default); err != nil {
return SoulSeedResult{Path: path}, err
}
return SoulSeedResult{Path: path, Action: SoulUpgraded}, nil
default:
return SoulSeedResult{Path: path, Action: SoulPreserved}, nil
}
}
// createSoulExclusive writes the starter without ever replacing a file that
// appeared since the caller decided the file was absent.
func createSoulExclusive(path, content string) error {
file, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
if err != nil {
return fmt.Errorf("soul: create %s: %w", path, err)
}
if _, err := file.WriteString(content); err != nil {
_ = file.Close()
return fmt.Errorf("soul: write %s: %w", path, err)
}
if err := file.Close(); err != nil {
return fmt.Errorf("soul: close %s: %w", path, err)
}
return nil
}
// replaceSoul swaps in the current document atomically, so a reader never
// observes a half-written SOUL and an interrupted upgrade leaves the previous
// content intact.
func replaceSoul(path, content string) error {
dir := filepath.Dir(path)
temp, err := os.CreateTemp(dir, ".SOUL.md.*")
if err != nil {
return fmt.Errorf("soul: create temp beside %s: %w", path, err)
}
tempName := temp.Name()
// Best-effort: a successful rename has already moved the file away.
defer func() { _ = os.Remove(tempName) }()
if err := temp.Chmod(0o600); err != nil {
_ = temp.Close()
return fmt.Errorf("soul: chmod %s: %w", tempName, err)
}
if _, err := temp.WriteString(content); err != nil {
_ = temp.Close()
return fmt.Errorf("soul: write %s: %w", tempName, err)
}
if err := temp.Close(); err != nil {
return fmt.Errorf("soul: close %s: %w", tempName, err)
}
if err := os.Rename(tempName, path); err != nil {
return fmt.Errorf("soul: replace %s: %w", path, err)
}
return nil
}
@@ -0,0 +1,266 @@
package configuration
import (
"os"
"path/filepath"
"strings"
"testing"
"github.com/samcharles93/archie-core/internal/domain/agent"
)
func TestConfigDirResolvesFilesAndDirectories(t *testing.T) {
t.Parallel()
dir := t.TempDir()
configFile := filepath.Join(dir, "config.toml")
if err := os.WriteFile(configFile, []byte(""), 0o600); err != nil {
t.Fatal(err)
}
tests := []struct {
name string
path string
want string
}{
{name: "a directory is used as given", path: dir, want: dir},
{name: "a file uses its directory", path: configFile, want: dir},
{name: "a missing path falls back to its directory", path: filepath.Join(dir, "missing", "config.toml"), want: filepath.Join(dir, "missing")},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
t.Parallel()
if got := ConfigDir(test.path); got != test.want {
t.Fatalf("ConfigDir(%q) = %q, want %q", test.path, got, test.want)
}
})
}
}
func TestSoulPath(t *testing.T) {
t.Parallel()
dir := t.TempDir()
if got, want := SoulPath(dir), filepath.Join(dir, SoulFilename); got != want {
t.Fatalf("SoulPath(dir) = %q, want %q", got, want)
}
configFile := filepath.Join(dir, "config.toml")
if got, want := SoulPath(configFile), filepath.Join(dir, SoulFilename); got != want {
t.Fatalf("SoulPath(file) = %q, want %q", got, want)
}
}
func TestSeedSoulCreatesStarterWhenAbsent(t *testing.T) {
t.Parallel()
dir := t.TempDir()
result, err := SeedSoul(dir, agent.ShippedSoul())
if err != nil {
t.Fatalf("SeedSoul() error = %v", err)
}
if result.Action != SoulCreated {
t.Fatalf("SeedSoul() action = %q, want %q", result.Action, SoulCreated)
}
if want := filepath.Join(dir, SoulFilename); result.Path != want {
t.Fatalf("SeedSoul() path = %q, want %q", result.Path, want)
}
got, err := os.ReadFile(result.Path)
if err != nil {
t.Fatal(err)
}
if string(got) != agent.ShippedSoul().Default {
t.Fatalf("seeded SOUL = %q, want the shipped default", got)
}
info, err := os.Stat(result.Path)
if err != nil {
t.Fatal(err)
}
if info.Mode().Perm() != 0o600 {
t.Fatalf("seeded SOUL mode = %v, want 0600", info.Mode().Perm())
}
}
func TestSeedSoulNeverClobbersAUserEdit(t *testing.T) {
t.Parallel()
dir := t.TempDir()
existing := "# My agent\n\nCall me Ada.\n"
writeSoulTestFile(t, dir, existing)
result, err := SeedSoul(dir, agent.ShippedSoul())
if err != nil {
t.Fatalf("SeedSoul() error = %v", err)
}
if result.Action != SoulPreserved {
t.Fatalf("SeedSoul() action = %q, want %q", result.Action, SoulPreserved)
}
if got := readSoulTestFile(t, dir); got != existing {
t.Fatalf("user edit was changed:\n got %q\nwant %q", got, existing)
}
}
func TestSeedSoulPreservesAnEmptyFile(t *testing.T) {
t.Parallel()
dir := t.TempDir()
writeSoulTestFile(t, dir, "")
result, err := SeedSoul(dir, agent.ShippedSoul())
if err != nil {
t.Fatalf("SeedSoul() error = %v", err)
}
if result.Action != SoulPreserved {
t.Fatalf("SeedSoul() action = %q, want %q (an empty file is an existing file)", result.Action, SoulPreserved)
}
if got := readSoulTestFile(t, dir); got != "" {
t.Fatalf("empty SOUL was changed to %q", got)
}
}
func TestSeedSoulLeavesACurrentDocumentUntouched(t *testing.T) {
t.Parallel()
dir := t.TempDir()
// A CRLF checkout of the current document is still current: normalising
// line endings must not make it look like a user edit, and it must not
// provoke a rewrite on every boot.
existing := strings.ReplaceAll(agent.ShippedSoul().Default, "\n", "\r\n")
writeSoulTestFile(t, dir, existing)
result, err := SeedSoul(dir, agent.ShippedSoul())
if err != nil {
t.Fatalf("SeedSoul() error = %v", err)
}
if result.Action != SoulCurrent {
t.Fatalf("SeedSoul() action = %q, want %q", result.Action, SoulCurrent)
}
if got := readSoulTestFile(t, dir); got != existing {
t.Fatalf("current SOUL was rewritten:\n got %q\nwant %q", got, existing)
}
}
func TestSeedSoulUpgradesASupersededTemplate(t *testing.T) {
t.Parallel()
const legacy = "# Archie\n\nOld starter identity.\n"
const current = "# Archie\n\nNew starter identity.\n"
doc := agent.SoulDocument{Default: current, Legacy: []string{legacy}}
dir := t.TempDir()
writeSoulTestFile(t, dir, strings.ReplaceAll(legacy, "\n", "\r\n"))
result, err := SeedSoul(dir, doc)
if err != nil {
t.Fatalf("SeedSoul() error = %v", err)
}
if result.Action != SoulUpgraded {
t.Fatalf("SeedSoul() action = %q, want %q", result.Action, SoulUpgraded)
}
if got := readSoulTestFile(t, dir); got != current {
t.Fatalf("upgraded SOUL = %q, want %q", got, current)
}
entries, err := os.ReadDir(dir)
if err != nil {
t.Fatal(err)
}
if len(entries) != 1 {
names := make([]string, 0, len(entries))
for _, entry := range entries {
names = append(names, entry.Name())
}
t.Fatalf("upgrade left files behind: %v", names)
}
}
func TestSeedSoulPreservesASymlink(t *testing.T) {
t.Parallel()
dir := t.TempDir()
target := filepath.Join(dir, "some-other-file.md")
userContent := "# User-managed\n"
if err := os.WriteFile(target, []byte(userContent), 0o600); err != nil {
t.Fatal(err)
}
link := filepath.Join(dir, SoulFilename)
if err := os.Symlink(target, link); err != nil {
t.Fatal(err)
}
result, err := SeedSoul(dir, agent.ShippedSoul())
if err != nil {
t.Fatalf("SeedSoul() error = %v", err)
}
if result.Action != SoulPreserved {
t.Fatalf("SeedSoul() action = %q, want %q", result.Action, SoulPreserved)
}
info, err := os.Lstat(link)
if err != nil {
t.Fatal(err)
}
if info.Mode()&os.ModeSymlink == 0 {
t.Fatal("SeedSoul replaced a symlink with a regular file")
}
got, err := os.ReadFile(target)
if err != nil {
t.Fatal(err)
}
if string(got) != userContent {
t.Fatalf("symlink target was changed to %q", got)
}
}
func TestSeedSoulTreatsAnOversizedFileAsAUserEdit(t *testing.T) {
t.Parallel()
dir := t.TempDir()
oversized := agent.ShippedSoul().Default + strings.Repeat("padding line\n", maxSoulReadBytes/8)
writeSoulTestFile(t, dir, oversized)
result, err := SeedSoul(dir, agent.ShippedSoul())
if err != nil {
t.Fatalf("SeedSoul() error = %v", err)
}
if result.Action != SoulPreserved {
t.Fatalf("SeedSoul() action = %q, want %q", result.Action, SoulPreserved)
}
if got := readSoulTestFile(t, dir); got != oversized {
t.Fatal("oversized SOUL was rewritten")
}
}
func TestSeedSoulSeedsBesideASelectedConfigFile(t *testing.T) {
t.Parallel()
dir := t.TempDir()
configFile := filepath.Join(dir, "config.toml")
if err := os.WriteFile(configFile, []byte(""), 0o600); err != nil {
t.Fatal(err)
}
result, err := SeedSoul(configFile, agent.ShippedSoul())
if err != nil {
t.Fatalf("SeedSoul() error = %v", err)
}
if result.Action != SoulCreated {
t.Fatalf("SeedSoul() action = %q, want %q", result.Action, SoulCreated)
}
if want := filepath.Join(dir, SoulFilename); result.Path != want {
t.Fatalf("SeedSoul() path = %q, want %q", result.Path, want)
}
}
func writeSoulTestFile(t *testing.T, dir, content string) {
t.Helper()
if err := os.WriteFile(filepath.Join(dir, SoulFilename), []byte(content), 0o600); err != nil {
t.Fatal(err)
}
}
func readSoulTestFile(t *testing.T, dir string) string {
t.Helper()
data, err := os.ReadFile(filepath.Join(dir, SoulFilename))
if err != nil {
t.Fatal(err)
}
return string(data)
}