Einheiten, Stufe 1: Organisationsbaum und Adressbuch als reine Rechnung (#683)
- UnitConfig (Id, Name, ParentId, LeaderAgentId, Goal, ToolCeiling, Defaults) in der Instanzkonfiguration neben den Agenten; AgentConfig.UnitId und UnitSinceUtc. Bewusst Konfiguration statt Datenbank: Die Werkzeugrechte der Agenten stehen schon dort, die Wahrheit ueber einen Agenten bleibt an einem Ort. Strukturaenderungen gehen ins Audit (Stufe 3). - OrgChart: Pfade, Tiefe, Leitung, effektive Leitung (die naechste Leitung darueber, wenn die eigene Einheit keine hat oder man sie selbst leitet), Adressbuch, Delegationstiefe aus dem Baum (Tiefe + 1, der eingestellte Wert bleibt Untergrenze), Rechte-Obergrenze als Schnittmenge entlang des Pfades, und eine Liste der Probleme (unbekannte Verweise, Zyklen, Leitung ist kein Mitglied, Werkzeuge ueber der Obergrenze). - Adressbuch: eigene Einheit und effektive Leitung; als Leitung die Leitungen der Untereinheiten (bei leitungslosen Untereinheiten deren Mitglieder), der Geschwistereinheiten und die eigene Leitung; die oberste Ebene und die Leitungen der obersten Einheiten sehen sich gegenseitig. Jede Linie ist in beide Richtungen begehbar. Ohne Einheiten sieht jeder jeden, wie bisher. Tests: OrgChartTests (20) am Onlinehandel-Beispiel aus dem Konzept. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Richard
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
dc11961805
commit
d014a20c38
@@ -10,6 +10,17 @@ public sealed class AgentConfig
|
||||
[JsonPropertyName("displayName")]
|
||||
public string DisplayName { get; set; } = "";
|
||||
|
||||
/// <summary>#683: The unit this agent belongs to; <c>null</c> for the top level.</summary>
|
||||
[JsonPropertyName("unitId")]
|
||||
public string? UnitId { get; set; }
|
||||
|
||||
/// <summary>
|
||||
/// #683: Since when the agent is in its unit (UTC) — so it can be told that it moved,
|
||||
/// and its lead that someone joined.
|
||||
/// </summary>
|
||||
[JsonPropertyName("unitSinceUtc")]
|
||||
public DateTime? UnitSinceUtc { get; set; }
|
||||
|
||||
[JsonPropertyName("model")]
|
||||
public string Model { get; set; } = "anthropic/claude-sonnet-4-5";
|
||||
|
||||
|
||||
@@ -172,6 +172,13 @@ public sealed class InstanceConfig
|
||||
[JsonPropertyName("agents")]
|
||||
public List<AgentConfig> Agents { get; set; } = new();
|
||||
|
||||
/// <summary>
|
||||
/// #683: Departments, teams, groups — the organisation tree. Empty means no structure:
|
||||
/// every agent can reach every other, as before units existed.
|
||||
/// </summary>
|
||||
[JsonPropertyName("units")]
|
||||
public List<UnitConfig> Units { get; set; } = new();
|
||||
|
||||
[JsonPropertyName("services")]
|
||||
public List<ServiceConfig> Services { get; set; } = new();
|
||||
}
|
||||
|
||||
@@ -0,0 +1,72 @@
|
||||
using System.Text.Json.Serialization;
|
||||
|
||||
namespace ClawdDotNet.Core.Config;
|
||||
|
||||
/// <summary>
|
||||
/// #683: A unit — department, team, group — as a node in the organisation tree.
|
||||
///
|
||||
/// <para><b>Stored in the instance configuration, next to the agents.</b> An agent's tools
|
||||
/// already live there; a unit's rules belong beside them, so the truth about an agent is in
|
||||
/// one place. Every structural change is written to the audit log by the administration,
|
||||
/// which is what the concept asked the database for.</para>
|
||||
///
|
||||
/// <para><b>No value here overrides an agent at run time</b> (Organisation-Konzept, section
|
||||
/// 3). <see cref="Defaults"/> are only the starting values for agents that join;
|
||||
/// <see cref="ToolCeiling"/> is checked when an agent's tools are written, never laid over
|
||||
/// them while it runs. What stands at the agent is what applies.</para>
|
||||
/// </summary>
|
||||
public sealed class UnitConfig
|
||||
{
|
||||
[JsonPropertyName("id")]
|
||||
public string Id { get; set; } = "";
|
||||
|
||||
[JsonPropertyName("name")]
|
||||
public string Name { get; set; } = "";
|
||||
|
||||
/// <summary>The parent unit; <c>null</c> for a top-level unit.</summary>
|
||||
[JsonPropertyName("parentId")]
|
||||
public string? ParentId { get; set; }
|
||||
|
||||
/// <summary>
|
||||
/// The agent leading this unit — one of its members. May be empty: then the nearest
|
||||
/// unit above that has a lead takes over.
|
||||
/// </summary>
|
||||
[JsonPropertyName("leaderAgentId")]
|
||||
public string? LeaderAgentId { get; set; }
|
||||
|
||||
/// <summary>What the unit exists for — the top of every task chain in it (#714).</summary>
|
||||
[JsonPropertyName("goal")]
|
||||
public string Goal { get; set; } = "";
|
||||
|
||||
/// <summary>
|
||||
/// The tools members of this unit may have at most; <c>null</c> means no ceiling. A
|
||||
/// ceiling applies to sub-units as well — the effective ceiling is the intersection
|
||||
/// along the path to the root.
|
||||
/// </summary>
|
||||
[JsonPropertyName("toolCeiling")]
|
||||
public List<string>? ToolCeiling { get; set; }
|
||||
|
||||
/// <summary>Starting values for agents that join this unit.</summary>
|
||||
[JsonPropertyName("defaults")]
|
||||
public UnitDefaults Defaults { get; set; } = new();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// #683: What an agent gets when it joins a unit. <c>null</c> leaves the agent's own value.
|
||||
/// Changing these does not touch existing members — writing a value into them is a
|
||||
/// separate, previewed step.
|
||||
/// </summary>
|
||||
public sealed class UnitDefaults
|
||||
{
|
||||
[JsonPropertyName("model")]
|
||||
public string? Model { get; set; }
|
||||
|
||||
[JsonPropertyName("dailyCostUsd")]
|
||||
public decimal? DailyCostUsd { get; set; }
|
||||
|
||||
[JsonPropertyName("dailyTokens")]
|
||||
public long? DailyTokens { get; set; }
|
||||
|
||||
[JsonPropertyName("whenExhausted")]
|
||||
public string? WhenExhausted { get; set; }
|
||||
}
|
||||
@@ -0,0 +1,322 @@
|
||||
using ClawdDotNet.Core.Config;
|
||||
|
||||
namespace ClawdDotNet.Core.Organisation;
|
||||
|
||||
/// <summary>
|
||||
/// #683: The organisation tree of an instance — units, members, leads — and everything that
|
||||
/// follows from it: who an agent can reach, who its lead is, how deep delegation may go,
|
||||
/// which tools a unit's members may have at most.
|
||||
///
|
||||
/// <para><b>One rule holds it together: an agent knows only its unit and its lead.</b>
|
||||
/// The cut of the address book is the organisation (Organisation-Konzept, section 3). It
|
||||
/// is computed from the tree, never configured, so it cannot be widened by accident —
|
||||
/// whoever wants an agent to reach further moves it in the tree, visibly.</para>
|
||||
///
|
||||
/// <para><b>Pure.</b> Built from the configuration, no I/O, no state. Every question is
|
||||
/// answered from the snapshot it was built from, so the engine, the administration and
|
||||
/// the tests all see the same organisation.</para>
|
||||
///
|
||||
/// <para><b>Without units nothing changes:</b> every agent reaches every other, as before.</para>
|
||||
/// </summary>
|
||||
public sealed class OrgChart
|
||||
{
|
||||
private readonly Dictionary<string, UnitConfig> _units;
|
||||
private readonly Dictionary<string, AgentConfig> _agents;
|
||||
private readonly Dictionary<string, List<UnitConfig>> _children;
|
||||
private readonly Dictionary<string, List<AgentConfig>> _members;
|
||||
|
||||
/// <summary>The key under which top-level units and agents without a unit are grouped.</summary>
|
||||
private const string Root = "";
|
||||
|
||||
public OrgChart(IEnumerable<UnitConfig> units, IEnumerable<AgentConfig> agents)
|
||||
{
|
||||
_units = new Dictionary<string, UnitConfig>(StringComparer.OrdinalIgnoreCase);
|
||||
foreach (var unit in units)
|
||||
_units.TryAdd(unit.Id, unit);
|
||||
|
||||
_agents = new Dictionary<string, AgentConfig>(StringComparer.OrdinalIgnoreCase);
|
||||
foreach (var agent in agents)
|
||||
_agents.TryAdd(agent.AgentId, agent);
|
||||
|
||||
_children = new Dictionary<string, List<UnitConfig>>(StringComparer.OrdinalIgnoreCase);
|
||||
foreach (var unit in _units.Values)
|
||||
{
|
||||
var parent = KnownParent(unit) ?? Root;
|
||||
if (!_children.TryGetValue(parent, out var list))
|
||||
_children[parent] = list = [];
|
||||
list.Add(unit);
|
||||
}
|
||||
|
||||
_members = new Dictionary<string, List<AgentConfig>>(StringComparer.OrdinalIgnoreCase);
|
||||
foreach (var agent in _agents.Values)
|
||||
{
|
||||
var key = KnownUnit(agent) ?? Root;
|
||||
if (!_members.TryGetValue(key, out var list))
|
||||
_members[key] = list = [];
|
||||
list.Add(agent);
|
||||
}
|
||||
}
|
||||
|
||||
public static OrgChart From(InstanceConfig instance) => new(instance.Units, instance.Agents);
|
||||
|
||||
/// <summary>Whether the instance has any structure at all.</summary>
|
||||
public bool HasUnits => _units.Count > 0;
|
||||
|
||||
public IReadOnlyCollection<UnitConfig> Units => _units.Values;
|
||||
|
||||
public UnitConfig? Unit(string? unitId)
|
||||
=> unitId is not null && _units.TryGetValue(unitId, out var unit) ? unit : null;
|
||||
|
||||
public AgentConfig? Agent(string agentId) => _agents.GetValueOrDefault(agentId);
|
||||
|
||||
/// <summary>The unit an agent belongs to; <c>null</c> for the top level (or an unknown unit).</summary>
|
||||
public UnitConfig? UnitOf(string agentId)
|
||||
=> _agents.TryGetValue(agentId, out var agent) ? Unit(KnownUnit(agent)) : null;
|
||||
|
||||
/// <summary>Direct sub-units; <c>null</c> asks for the top-level units.</summary>
|
||||
public IReadOnlyList<UnitConfig> Children(string? unitId)
|
||||
=> _children.TryGetValue(unitId ?? Root, out var list) ? list : [];
|
||||
|
||||
/// <summary>Direct members; <c>null</c> asks for the agents on the top level.</summary>
|
||||
public IReadOnlyList<AgentConfig> MembersOf(string? unitId)
|
||||
=> _members.TryGetValue(unitId ?? Root, out var list) ? list : [];
|
||||
|
||||
/// <summary>The units above, nearest first — not including the unit itself.</summary>
|
||||
public IReadOnlyList<UnitConfig> Ancestors(string unitId)
|
||||
{
|
||||
var result = new List<UnitConfig>();
|
||||
var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase) { unitId };
|
||||
var current = Unit(unitId);
|
||||
while (current is not null && KnownParent(current) is { } parentId && seen.Add(parentId))
|
||||
{
|
||||
current = _units[parentId];
|
||||
result.Add(current);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
/// <summary>"Marketing / Marketplaces / Amazon".</summary>
|
||||
public string PathOf(string unitId)
|
||||
{
|
||||
if (Unit(unitId) is not { } unit)
|
||||
return "";
|
||||
var names = Ancestors(unitId).Select(u => u.Name).Reverse().Append(unit.Name);
|
||||
return string.Join(" / ", names);
|
||||
}
|
||||
|
||||
/// <summary>Depth of a unit: a top-level unit is 1.</summary>
|
||||
public int Depth(string unitId) => Unit(unitId) is null ? 0 : Ancestors(unitId).Count + 1;
|
||||
|
||||
/// <summary>The deepest unit's depth; 0 without units.</summary>
|
||||
public int TreeDepth => _units.Keys.Select(Depth).DefaultIfEmpty(0).Max();
|
||||
|
||||
/// <summary>
|
||||
/// How many hand-overs a delegation chain may have: enough to go from the top to the
|
||||
/// bottom of the tree and one step further, and never less than the configured floor.
|
||||
/// Before #683 this was a fixed 3 — lead, department, team, agent already used it up.
|
||||
/// </summary>
|
||||
public int DelegationDepth(int configuredFloor) => Math.Max(configuredFloor, TreeDepth + 1);
|
||||
|
||||
/// <summary>The lead of a unit, if it has one that is actually a member.</summary>
|
||||
public AgentConfig? LeaderOf(string? unitId)
|
||||
{
|
||||
if (Unit(unitId) is not { LeaderAgentId: { Length: > 0 } leaderId } unit)
|
||||
return null;
|
||||
return _agents.TryGetValue(leaderId, out var leader)
|
||||
&& string.Equals(KnownUnit(leader), unit.Id, StringComparison.OrdinalIgnoreCase)
|
||||
? leader
|
||||
: null;
|
||||
}
|
||||
|
||||
/// <summary>The unit this agent leads, if any.</summary>
|
||||
public UnitConfig? LedBy(string agentId)
|
||||
{
|
||||
var unit = UnitOf(agentId);
|
||||
return unit is not null && LeaderOf(unit.Id) is { } leader
|
||||
&& string.Equals(leader.AgentId, agentId, StringComparison.OrdinalIgnoreCase)
|
||||
? unit
|
||||
: null;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Who the agent answers to: the lead of its unit — or, if it leads that unit itself or
|
||||
/// the unit has no lead, the nearest lead above. <c>null</c> means: the human.
|
||||
/// </summary>
|
||||
public AgentConfig? EffectiveLeaderOf(string agentId)
|
||||
{
|
||||
var unit = UnitOf(agentId);
|
||||
if (unit is null)
|
||||
return null;
|
||||
|
||||
foreach (var candidate in new[] { unit }.Concat(Ancestors(unit.Id)))
|
||||
{
|
||||
if (LeaderOf(candidate.Id) is { } leader
|
||||
&& !string.Equals(leader.AgentId, agentId, StringComparison.OrdinalIgnoreCase))
|
||||
return leader;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Everyone the agent may address — the cut of the address book (section 3):
|
||||
/// <list type="bullet">
|
||||
/// <item>the members of its own unit and its effective lead;</item>
|
||||
/// <item>as a lead: the leads of its sub-units — and, where a sub-unit has no lead, that
|
||||
/// sub-unit's members, because this lead is who they answer to — and the leads of its
|
||||
/// sibling units;</item>
|
||||
/// <item>on the top level: each other and the leads of the top-level units, both ways.</item>
|
||||
/// </list>
|
||||
/// Without units: everyone.
|
||||
/// </summary>
|
||||
public IReadOnlySet<string> AddressBook(string agentId)
|
||||
{
|
||||
var result = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
|
||||
if (!_agents.ContainsKey(agentId))
|
||||
return result;
|
||||
|
||||
if (!HasUnits)
|
||||
{
|
||||
result.UnionWith(_agents.Keys);
|
||||
result.Remove(agentId);
|
||||
return result;
|
||||
}
|
||||
|
||||
var unit = UnitOf(agentId);
|
||||
foreach (var member in MembersOf(unit?.Id))
|
||||
result.Add(member.AgentId);
|
||||
|
||||
if (EffectiveLeaderOf(agentId) is { } lead)
|
||||
result.Add(lead.AgentId);
|
||||
|
||||
if (unit is null)
|
||||
{
|
||||
// Top level: the house management reaches the heads of the top-level units.
|
||||
AddLeadsBelow(null, result);
|
||||
}
|
||||
else if (LedBy(agentId) is { } led)
|
||||
{
|
||||
AddLeadsBelow(led.Id, result);
|
||||
|
||||
foreach (var sibling in Children(KnownParent(led)))
|
||||
{
|
||||
if (!string.Equals(sibling.Id, led.Id, StringComparison.OrdinalIgnoreCase)
|
||||
&& LeaderOf(sibling.Id) is { } siblingLead)
|
||||
result.Add(siblingLead.AgentId);
|
||||
}
|
||||
|
||||
// A top-level lead reaches the top level — the same line, seen from below.
|
||||
if (KnownParent(led) is null)
|
||||
foreach (var member in MembersOf(null))
|
||||
result.Add(member.AgentId);
|
||||
}
|
||||
|
||||
result.Remove(agentId);
|
||||
return result;
|
||||
}
|
||||
|
||||
public bool CanAddress(string fromAgentId, string toAgentId)
|
||||
=> AddressBook(fromAgentId).Contains(toAgentId);
|
||||
|
||||
/// <summary>
|
||||
/// The tools a member of the unit may have at most: the intersection of the ceilings
|
||||
/// along the path to the top. <c>null</c> means no ceiling anywhere on the path.
|
||||
/// </summary>
|
||||
public IReadOnlySet<string>? ToolCeiling(string? unitId)
|
||||
{
|
||||
if (Unit(unitId) is not { } unit)
|
||||
return null;
|
||||
|
||||
HashSet<string>? ceiling = null;
|
||||
foreach (var node in new[] { unit }.Concat(Ancestors(unit.Id)))
|
||||
{
|
||||
if (node.ToolCeiling is null)
|
||||
continue;
|
||||
if (ceiling is null)
|
||||
ceiling = new HashSet<string>(node.ToolCeiling, StringComparer.OrdinalIgnoreCase);
|
||||
else
|
||||
ceiling.IntersectWith(node.ToolCeiling);
|
||||
}
|
||||
return ceiling;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// What is wrong with the structure — empty when it is sound. Checked when the
|
||||
/// administration writes and when an instance starts; the tree is still usable with
|
||||
/// problems (unknown references count as top level), but they are named.
|
||||
/// </summary>
|
||||
public IReadOnlyList<string> Problems()
|
||||
{
|
||||
var problems = new List<string>();
|
||||
|
||||
foreach (var unit in _units.Values)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(unit.Id))
|
||||
problems.Add("A unit has no id.");
|
||||
if (unit.ParentId is { Length: > 0 } parentId && !_units.ContainsKey(parentId))
|
||||
problems.Add($"Unit '{unit.Id}' names the parent '{parentId}', which does not exist.");
|
||||
if (IsInCycle(unit.Id))
|
||||
problems.Add($"Unit '{unit.Id}' is part of a cycle — a unit cannot contain itself.");
|
||||
if (unit.LeaderAgentId is { Length: > 0 } leaderId && LeaderOf(unit.Id) is null)
|
||||
problems.Add(_agents.ContainsKey(leaderId)
|
||||
? $"Unit '{unit.Id}' names '{leaderId}' as lead, but that agent is not a member of it."
|
||||
: $"Unit '{unit.Id}' names the lead '{leaderId}', which does not exist.");
|
||||
}
|
||||
|
||||
foreach (var agent in _agents.Values)
|
||||
{
|
||||
if (agent.UnitId is { Length: > 0 } unitId && !_units.ContainsKey(unitId))
|
||||
problems.Add($"Agent '{agent.AgentId}' belongs to the unit '{unitId}', which does not exist.");
|
||||
|
||||
if (ToolCeiling(KnownUnit(agent)) is { } ceiling)
|
||||
{
|
||||
var beyond = agent.Tools.Keys.Where(t => !ceiling.Contains(t)).ToList();
|
||||
if (beyond.Count > 0)
|
||||
problems.Add($"Agent '{agent.AgentId}' has tools beyond its unit's ceiling: {string.Join(", ", beyond)}.");
|
||||
}
|
||||
}
|
||||
|
||||
return problems;
|
||||
}
|
||||
|
||||
// ─── helpers ───
|
||||
|
||||
private void AddLeadsBelow(string? unitId, HashSet<string> into)
|
||||
{
|
||||
foreach (var child in Children(unitId))
|
||||
{
|
||||
if (LeaderOf(child.Id) is { } lead)
|
||||
{
|
||||
into.Add(lead.AgentId);
|
||||
continue;
|
||||
}
|
||||
|
||||
// No lead there: its members answer to the lead above — so this one sees them,
|
||||
// and looks further down for the next leads.
|
||||
foreach (var member in MembersOf(child.Id))
|
||||
into.Add(member.AgentId);
|
||||
AddLeadsBelow(child.Id, into);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>The parent id if it names an existing unit and does not close a cycle.</summary>
|
||||
private string? KnownParent(UnitConfig unit)
|
||||
=> unit.ParentId is { Length: > 0 } parentId && _units.ContainsKey(parentId) && !IsInCycle(unit.Id)
|
||||
? _units[parentId].Id
|
||||
: null;
|
||||
|
||||
private string? KnownUnit(AgentConfig agent)
|
||||
=> agent.UnitId is { Length: > 0 } unitId && _units.TryGetValue(unitId, out var unit) ? unit.Id : null;
|
||||
|
||||
private bool IsInCycle(string unitId)
|
||||
{
|
||||
var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
|
||||
var current = unitId;
|
||||
while (current is not null && _units.TryGetValue(current, out var unit))
|
||||
{
|
||||
if (!seen.Add(current))
|
||||
return true;
|
||||
current = unit.ParentId is { Length: > 0 } p ? p : null;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user