Merge pull request #112 from isartor-ai/codex/fix-agent-registry-write-path

fix(agents): write saved profiles to writable overlay

Author: robinson

docker/docker-compose.quickstart.yml

@@ -65,6 +65,7 @@ services:
       Storage__RootPath: /app/storage
       Agents__Skills__SkillsDirectory: /app/skills
       Agents__Registry__AgentsDirectory: /app/agents
+      Agents__Registry__WritableAgentsDirectory: /app/storage/agents
       # Tokenless: deterministic mock model — no API key required.
       Anthropic__Provider: "mock"
       # No external integrations needed for the quickstart.
@@ -77,6 +78,7 @@ services:
       Jwt__Audience: "autofac-dev"
       Jwt__DevTokensEnabled: "true"
     volumes:
+      - api_storage:/app/storage
       - ../.github/skills:/app/skills:ro
       - ../agents:/app/agents:ro
     depends_on:
@@ -100,3 +102,6 @@ services:
     ports: ["3002:80"]
     depends_on:
       api: { condition: service_healthy }
+
+volumes:
+  api_storage:

docker/docker-compose.yml

@@ -75,6 +75,7 @@ services:
       Storage__RootPath: /app/storage
       Agents__Skills__SkillsDirectory: /app/skills
       Agents__Registry__AgentsDirectory: /app/agents
+      Agents__Registry__WritableAgentsDirectory: /app/storage/agents
       Sandboxes__Docker__Enabled: "false"
       Sandboxes__Docker__DockerEndpoint: "unix:///var/run/docker.sock"
       Tracing__OtlpEndpoint: "http://jaeger:4317"

docs/agent-and-skill-authoring.md

@@ -5,6 +5,13 @@ configured directories (`Agents:Registry:AgentsDirectory` and
 `Agents:Skills:SkillsDirectory`). The defaults ship under `agents/` and
 `.github/skills/`.
 
+When the bundled agents directory is mounted read-only, set
+`Agents:Registry:WritableAgentsDirectory` to a writable overlay directory.
+Autofac loads `AgentsDirectory` first and then `WritableAgentsDirectory`, so
+admin UI saves can customize or add agents without mutating the shipped files.
+If `WritableAgentsDirectory` is omitted, saves use `AgentsDirectory` for
+backward compatibility.
+
 ## Agents (`agents/<id>/AGENT.md`)
 
 An agent profile declares what an agent is allowed to do; the Markdown body is

src/Autofac.Agents/AgentOptions.cs

@@ -10,4 +10,11 @@ public sealed class AgentOptions
     /// built-in agents of the same id. Defaults to empty (no file agents loaded).
     /// </summary>
     public string AgentsDirectory { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Absolute or relative path where UI/API-authored agent overlays are written.
+    /// Defaults to <see cref="AgentsDirectory"/> for backward compatibility. Set
+    /// this separately when <see cref="AgentsDirectory"/> is mounted read-only.
+    /// </summary>
+    public string WritableAgentsDirectory { get; set; } = string.Empty;
 }

src/Autofac.Agents/AgentRegistryPaths.cs

@@ -7,6 +7,8 @@ public sealed record AgentRegistryPaths(
     string AgentsDirectory,
     string SkillsDirectory)
 {
+    public string WritableAgentsDirectory { get; init; } = AgentsDirectory;
+
     public static AgentRegistryPaths Resolve(IConfiguration configuration)
     {
         ArgumentNullException.ThrowIfNull(configuration);
@@ -23,6 +25,12 @@ public static AgentRegistryPaths Resolve(IConfiguration configuration)
             agentsDirectory = Path.GetFullPath("agents");
         }
 
+        var writableAgentsDirectory = ResolveDirectory(agentOptions.WritableAgentsDirectory);
+        if (string.IsNullOrWhiteSpace(writableAgentsDirectory))
+        {
+            writableAgentsDirectory = agentsDirectory;
+        }
+
         var skillsDirectory = ResolveDirectory(skillOptions.SkillsDirectory);
         if (string.IsNullOrWhiteSpace(skillsDirectory))
         {
@@ -33,7 +41,10 @@ public static AgentRegistryPaths Resolve(IConfiguration configuration)
             }
         }
 
-        return new AgentRegistryPaths(agentsDirectory, skillsDirectory);
+        return new AgentRegistryPaths(agentsDirectory, skillsDirectory)
+        {
+            WritableAgentsDirectory = writableAgentsDirectory
+        };
     }
 
     private static string ResolveDirectory(string? configuredDirectory)

src/Autofac.Agents/DependencyInjection.cs

@@ -20,7 +20,7 @@ public static IServiceCollection AddAutofacAgents(
     {
         var paths = AgentRegistryPaths.Resolve(configuration);
         services.AddSingleton(paths);
-        services.AddSingleton<IAgentRegistry>(new FileAgentRegistry(paths.AgentsDirectory));
+        services.AddSingleton<IAgentRegistry>(new FileAgentRegistry(paths));
         services.AddSingleton<ISkillRepository>(new SkillRepository(paths.SkillsDirectory));
         services.AddSingleton<IAgentRegistryEditor, FileAgentRegistryEditor>();
         services.AddSingleton<IAgentPromptAssembler, AgentPromptAssembler>();

src/Autofac.Agents/IAgentRegistry.cs

@@ -29,6 +29,11 @@ public FileAgentRegistry(string agentsDirectory)
     {
     }
 
+    public FileAgentRegistry(AgentRegistryPaths paths)
+        : this(() => LoadFromDirectories(paths))
+    {
+    }
+
     private FileAgentRegistry(Func<IReadOnlyList<AgentProfile>> fileProfileLoader)
     {
         _fileProfileLoader = fileProfileLoader;
@@ -58,4 +63,22 @@ private Dictionary<string, AgentProfile> BuildCatalog()
 
         return byId;
     }
+
+    private static IReadOnlyList<AgentProfile> LoadFromDirectories(AgentRegistryPaths paths)
+    {
+        ArgumentNullException.ThrowIfNull(paths);
+
+        var profiles = new List<AgentProfile>();
+        var directories = new[] { paths.AgentsDirectory, paths.WritableAgentsDirectory }
+            .Where(static directory => !string.IsNullOrWhiteSpace(directory))
+            .Select(Path.GetFullPath)
+            .Distinct(StringComparer.OrdinalIgnoreCase);
+
+        foreach (var directory in directories)
+        {
+            profiles.AddRange(MarkdownAgentLoader.LoadFromDirectory(directory));
+        }
+
+        return profiles;
+    }
 }

src/Autofac.Agents/IAgentRegistryEditor.cs

@@ -45,7 +45,7 @@ public ManagedAgentDocument Save(AgentProfile profile)
             throw new InvalidOperationException("Agent id is required.");
         }
 
-        var destinationPath = GetAgentFilePath(profile.AgentId);
+        var destinationPath = GetWritableAgentFilePath(profile.AgentId);
         Directory.CreateDirectory(Path.GetDirectoryName(destinationPath)!);
 
         var rawMarkdown = AgentMarkdownSerializer.Serialize(profile);
@@ -74,7 +74,7 @@ public ManagedAgentDocument Upload(string fileName, string content)
             throw new InvalidOperationException("Uploaded agent file must declare an id in frontmatter or use a named file.");
         }
 
-        var destinationPath = GetAgentFilePath(parsed.AgentId);
+        var destinationPath = GetWritableAgentFilePath(parsed.AgentId);
         Directory.CreateDirectory(Path.GetDirectoryName(destinationPath)!);
         File.WriteAllText(destinationPath, content.TrimEnd() + Environment.NewLine, new UTF8Encoding(encoderShouldEmitUTF8Identifier: false));
 
@@ -84,7 +84,7 @@ public ManagedAgentDocument Upload(string fileName, string content)
 
     private ManagedAgentDocument ToDocument(AgentProfile profile)
     {
-        var effectiveFilePath = GetAgentFilePath(profile.AgentId);
+        var effectiveFilePath = GetWritableAgentFilePath(profile.AgentId);
         if (File.Exists(effectiveFilePath))
         {
             return new ManagedAgentDocument(
@@ -94,14 +94,28 @@ private ManagedAgentDocument ToDocument(AgentProfile profile)
                 effectiveFilePath);
         }
 
+        var sourceFilePath = GetConfiguredAgentFilePath(profile.AgentId);
+        if (!string.Equals(sourceFilePath, effectiveFilePath, StringComparison.OrdinalIgnoreCase) &&
+            File.Exists(sourceFilePath))
+        {
+            return new ManagedAgentDocument(
+                profile,
+                File.ReadAllText(sourceFilePath, Encoding.UTF8),
+                sourceFilePath,
+                sourceFilePath);
+        }
+
         return new ManagedAgentDocument(
             profile,
             AgentMarkdownSerializer.Serialize(profile),
             effectiveFilePath,
             null);
     }
 
-    private string GetAgentFilePath(string agentId) =>
+    private string GetWritableAgentFilePath(string agentId) =>
+        Path.Combine(_paths.WritableAgentsDirectory, NormalizeAgentId(agentId), "AGENT.md");
+
+    private string GetConfiguredAgentFilePath(string agentId) =>
         Path.Combine(_paths.AgentsDirectory, NormalizeAgentId(agentId), "AGENT.md");
 
     private static string DeriveDirectoryId(string fileName)

tests/Autofac.Api.Tests/AgentsControllerTests.cs

@@ -65,6 +65,43 @@ public void Upsert_WritesOverlayFileAndReturnsSavedAgent()
         Assert.True(File.Exists(Path.Combine(fixture.AgentsDirectory, "custom-agent", "AGENT.md")));
     }
 
+    [Fact]
+    public void Upsert_WhenWritableAgentDirectoryDiffers_WritesOverlayFileAndReloadsSavedAgent()
+    {
+        using var fixture = new AgentRegistryFixture(useWritableOverlay: true);
+        var controller = fixture.CreateController();
+
+        var result = controller.Upsert("business-analyst", new UpsertAgentRequest(
+            AgentId: "business-analyst",
+            Name: "Business Analyst",
+            Description: "Turns issues into requirements.",
+            Category: "analysis",
+            Runner: "agent-model",
+            Skills:
+            [
+                new AgentSkillBinding(
+                    "requirements",
+                    "Requirements",
+                    "Shape requirements.",
+                    ["requirement-design"],
+                    "test-driven-development")
+            ],
+            SupportedActions: ["requirement-design"],
+            SupportedEnvironments: ["all"],
+            SupportedPolicyTags: ["requirement-design"],
+            SystemPrompt: "Write crisp requirements."));
+
+        var ok = Assert.IsType<OkObjectResult>(result);
+        var detail = Assert.IsType<AgentDetail>(ok.Value);
+
+        var sourcePath = Path.Combine(fixture.AgentsDirectory, "business-analyst", "AGENT.md");
+        var overlayPath = Path.Combine(fixture.WritableAgentsDirectory, "business-analyst", "AGENT.md");
+        Assert.False(File.Exists(sourcePath));
+        Assert.True(File.Exists(overlayPath));
+        Assert.Equal("test-driven-development", Assert.Single(detail.Skills).SkillManifestId);
+        Assert.Equal(Path.GetFullPath(overlayPath), detail.EffectiveFilePath);
+    }
+
     [Fact]
     public void Upload_ParsesAgentMarkdownAndCreatesAgentFile()
     {
@@ -167,12 +204,14 @@ public void Upsert_WhenSandboxProfileIsKnown_PersistsAndReturnsIt()
 
     private sealed class AgentRegistryFixture : IDisposable
     {
-        public AgentRegistryFixture()
+        public AgentRegistryFixture(bool useWritableOverlay = false)
         {
             Root = Path.Combine(Path.GetTempPath(), $"agent_registry_{Guid.NewGuid():N}");
             AgentsDirectory = Path.Combine(Root, "agents");
+            WritableAgentsDirectory = useWritableOverlay ? Path.Combine(Root, "agent-overlays") : AgentsDirectory;
             SkillsDirectory = Path.Combine(Root, "skills");
             Directory.CreateDirectory(AgentsDirectory);
+            Directory.CreateDirectory(WritableAgentsDirectory);
             Directory.CreateDirectory(Path.Combine(SkillsDirectory, "test-driven-development"));
             File.WriteAllText(Path.Combine(SkillsDirectory, "test-driven-development", "SKILL.md"), """
                 ---
@@ -183,8 +222,11 @@ public AgentRegistryFixture()
                 Skill body.
                 """);
 
-            Paths = new AgentRegistryPaths(AgentsDirectory, SkillsDirectory);
-            Registry = new FileAgentRegistry(AgentsDirectory);
+            Paths = new AgentRegistryPaths(AgentsDirectory, SkillsDirectory)
+            {
+                WritableAgentsDirectory = WritableAgentsDirectory
+            };
+            Registry = new FileAgentRegistry(Paths);
             Skills = new SkillRepository(SkillsDirectory);
             Editor = new FileAgentRegistryEditor(Paths, Registry);
         }
@@ -193,6 +235,8 @@ Skill body.
 
         public string AgentsDirectory { get; }
 
+        public string WritableAgentsDirectory { get; }
+
         public string SkillsDirectory { get; }
 
         public AgentRegistryPaths Paths { get; }