Einheiten, Stufe 2: das Adressbuch durchsetzen und jedem Agenten seinen Platz sagen (#683)

Durchgesetzt vom Code, nicht nur im Prompt beschrieben: - Nachricht und Spawn an einen Agenten ausserhalb des Adressbuchs werden vor jedem Modellaufruf abgelehnt; die Antwort nennt den offenen Weg (die eigene Leitung, sonst @human). - list_agents zeigt nur noch das Adressbuch. - task_create und task_update pruefen die Zuweisung an einen Agenten gegen dasselbe Adressbuch; sonst liesse es sich ueber eine Aufgabe umgehen. - Die Delegationstiefe folgt der Tiefe des Baums (Tiefe + 1), der eingestellte Wert bleibt Untergrenze. Unterrichtet werden, wie das Konzept verlangt: - OrgBriefing erzeugt einen Abschnitt "# Organisation" im Systemprompt: Einheit mit Pfad und Ziel, seit wann (mit Hinweis, wenn frisch), die effektive Leitung oder "@human", als Leitung die Untereinheiten und neue Mitglieder, und wen man sonst erreicht. Er ist immer wahr, weil er aus dem Baum kommt; ein Umzug aendert ihn von selbst. - In einem laufenden Chat wird nur dieser Abschnitt ersetzt; der uebrige Systemprompt bleibt, wie er war (#193). - Ohne Einheiten gibt es keinen Abschnitt und keine Einschraenkung. Bestehende Instanzen behalten ihren Prompt und ihren Prompt-Cache. AppHost setzt den Organisationsbaum als Provider (frisch je Frage, eine Aenderung gilt ab dem naechsten Lauf) und protokolliert Probleme der Struktur beim Start. Tests: AddressBookEnforcementTests (10), AssignmentReachTests (4). 1.317 gruen. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 12:43:10 +02:00
parent d014a20c38
commit 626fc8d593
7 changed files with 503 additions and 6 deletions
@@ -0,0 +1,124 @@
+using System.Text;
+
+namespace ClawdDotNet.Core.Organisation;
+
+/// <summary>
+/// #683: The "Organisation" section of an agent's system prompt — its unit, its lead, whom it
+/// can reach, and what changed recently.
+///
+/// <para><b>Why the code writes it and not the agent's own texts.</b> The concept demands
+/// that agents are told when they move, and warns: an agent that has to infer its lead from
+/// a prompt escalates to the wrong place. A section generated from the tree is always true —
+/// a move changes it by itself, for the agent that moved and for both leads.</para>
+///
+/// <para><b>Without units there is no section</b>, so instances without a structure keep
+/// exactly the prompt they had — and the prompt cache that goes with it.</para>
+/// </summary>
+public static class OrgBriefing
+{
+    /// <summary>Starts the section; also how an existing chat context finds it to replace it.</summary>
+    public const string Heading = "# Organisation";
+
+    /// <summary>How long a move or a new colleague is pointed out.</summary>
+    public static readonly TimeSpan RecentChange = TimeSpan.FromDays(7);
+
+    private const int MaxDescription = 120;
+
+    public static string? For(OrgChart org, string agentId, DateTime nowUtc)
+    {
+        if (!org.HasUnits || org.Agent(agentId) is not { } agent)
+            return null;
+
+        var sb = new StringBuilder();
+        sb.AppendLine(Heading);
+
+        var unit = org.UnitOf(agentId);
+        if (unit is null)
+        {
+            sb.AppendLine("You are on the top level of this instance, above all units.");
+        }
+        else
+        {
+            sb.Append($"You belong to the unit \"{unit.Name}\" ({org.PathOf(unit.Id)})");
+            if (agent.UnitSinceUtc is { } since)
+            {
+                sb.Append($", since {since:yyyy-MM-dd}");
+                if (nowUtc - since < RecentChange)
+                    sb.Append(" — this is recent: your lead, your colleagues and possibly your tools changed");
+            }
+            sb.AppendLine(".");
+
+            if (!string.IsNullOrWhiteSpace(unit.Goal))
+                sb.AppendLine($"Goal of your unit: {unit.Goal.Trim()}");
+        }
+
+        var lead = org.EffectiveLeaderOf(agentId);
+        if (lead is not null)
+            sb.AppendLine($"Your lead: {Name(lead)}. Questions, problems and anything outside your unit go to your lead.");
+        else
+            sb.AppendLine("There is no lead agent above you. What you cannot decide goes to a human: create a task for @human.");
+
+        if (org.LedBy(agentId) is { } led)
+        {
+            sb.AppendLine($"You lead the unit \"{led.Name}\". Delegate within it, and hand what goes beyond it to your own lead.");
+            var subUnits = org.Children(led.Id);
+            if (subUnits.Count > 0)
+            {
+                sb.AppendLine("Its sub-units: " + string.Join("; ", subUnits.Select(u =>
+                    org.LeaderOf(u.Id) is { } l ? $"{u.Name} (lead: {l.AgentId})" : $"{u.Name} (no lead — its members report to you)")) + ".");
+            }
+
+            var joined = org.MembersOf(led.Id)
+                .Where(m => m.AgentId != agentId && m.UnitSinceUtc is { } s && nowUtc - s < RecentChange)
+                .ToList();
+            if (joined.Count > 0)
+                sb.AppendLine("New in your unit: " + string.Join(", ", joined.Select(m => $"{m.AgentId} since {m.UnitSinceUtc:yyyy-MM-dd}")) + ".");
+        }
+
+        var contacts = org.AddressBook(agentId)
+            .Where(id => lead is null || !string.Equals(id, lead.AgentId, StringComparison.OrdinalIgnoreCase))
+            .Select(id => org.Agent(id)!)
+            .OrderBy(a => a.AgentId, StringComparer.OrdinalIgnoreCase)
+            .ToList();
+
+        if (contacts.Count > 0)
+        {
+            sb.AppendLine("You can also reach:");
+            foreach (var contact in contacts)
+                sb.AppendLine($"- {Name(contact)}{Describe(contact.Description)}");
+        }
+
+        sb.Append("Agents not named here cannot be reached from your position — go through your lead.");
+        return sb.ToString();
+    }
+
+    /// <summary>
+    /// Replaces the organisation section of a system prompt, appends it, or removes it —
+    /// leaving everything before it untouched. Existing chat contexts keep their system
+    /// prompt otherwise (#193); only this section follows the structure.
+    /// </summary>
+    public static string WithSection(string systemPrompt, string? section)
+    {
+        var start = systemPrompt.IndexOf("\n\n" + Heading + "\n", StringComparison.Ordinal);
+        var basePrompt = start >= 0 ? systemPrompt[..start] : systemPrompt;
+        if (start < 0 && systemPrompt.StartsWith(Heading + "\n", StringComparison.Ordinal))
+            basePrompt = "";
+
+        if (string.IsNullOrWhiteSpace(section))
+            return basePrompt;
+        return basePrompt.Length == 0 ? section : basePrompt + "\n\n" + section;
+    }
+
+    private static string Name(Config.AgentConfig agent)
+        => string.IsNullOrWhiteSpace(agent.DisplayName) || agent.DisplayName == agent.AgentId
+            ? agent.AgentId
+            : $"{agent.DisplayName} ({agent.AgentId})";
+
+    private static string Describe(string? description)
+    {
+        if (string.IsNullOrWhiteSpace(description))
+            return "";
+        var line = description.ReplaceLineEndings(" ").Trim();
+        return " — " + (line.Length > MaxDescription ? line[..MaxDescription] + "…" : line);
+    }
+}