Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ VotingPlugin Control is designed to manage and troubleshoot a VotingPlugin netwo

- Run guided setup for standalone and proxy/backend networks.
- Configure common settings through searchable presets.
- Let Codex CLI or Claude Code read and preview a named backend vote site or automatic site-creation policy for up to ten explicit backends through opt-in local MCP, then review and apply it in Control. Separately grant agents scoped topology, Network Doctor checks, proxy routing previews, non-vote transport checks, and typed General Settings and Vote Sites editor previews. See [agent setup](docs/agent-setup.md).
- Let Codex CLI or Claude Code read and preview a named backend vote site or automatic site-creation policy for up to ten explicit backends through opt-in local MCP, then review and apply it in Control. Separately grant agents scoped topology, Network Doctor checks, proxy routing previews, non-vote transport checks, and typed General Settings, Vote Sites, and Rewards editor previews. See [agent setup](docs/agent-setup.md).
- Set up or synchronize Vote Sites while preserving existing rewards and sensitive values.
- Configure automatic Vote Site creation.
- Configure VoteLogging and retention.
Expand Down
11 changes: 11 additions & 0 deletions docs/agent-setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,3 +118,14 @@ more changed fields. Remove takes no fields. A site with inline Rewards or unrev
The proposal preserves unrelated sites and sections. Control checks the current redacted source and complete changed
paths against the reviewed proposal before making browser approval available. MCP returns typed fields and a Rewards
presence indicator, and omits raw documents and approval material.


## Optional typed Rewards editor

Grant **Read and preview typed Reward fields** and **Track operations** to use `read_reward_field`
and `preview_reward_field` on one Bukkit backend. Select an exact `siteKey` for an inline reward with
`config.files.v1`, or an exact `rewardName` for an enrolled named reward file with `config.reward-files.v1`.
Select an existing money, chance, player or broadcast message, or named item material or amount field.
Preview uses that read operation ID and one replacement scalar. Control checks the source, revision and exact
changed path before browser approval. Command payloads, reward creation or removal, raw files, and execution
are outside this tool surface.
4 changes: 2 additions & 2 deletions docs/mcp-network-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ A proxy-network grant limits where an agent may use MCP. The negotiated node cap
| --- | --- | --- |
| Enrolled identity, liveness, accepted capabilities, proxy/backend presence and topology | Bounded discovery and topology, with proxy snapshot freshness and truncation indicators | Extend large-network link pagination |
| Network Doctor, overview, diagnostics, vote-site health, vote-log summary/search/trace, exact player lookup, site resolution, reward simulation | Network Doctor status and read-only observation refresh with a separate health action | Further diagnostic projections. Player and log data need separate projections and access decisions |
| Bukkit managed YAML, split VoteSites, named reward files, supported file comments, General Settings, typed Vote Sites and Rewards | Typed backend and proxy General Settings, plus a named-site guided preview and typed Vote Sites editor | Add typed editor tools using their existing validators, per-target revisions, and bounded results |
| Bukkit managed YAML, split VoteSites, named reward files, supported file comments, General Settings, typed Vote Sites and Rewards | Typed backend and proxy General Settings, plus a named-site guided preview and typed Vote Sites and scalar Rewards editors | Add typed editor tools using their existing validators, per-target revisions, and bounded results |
| Quick setup v1/v2, standalone/proxy setup, common settings, auto-create, vote logging, Vote Party, rewards and VoteSites sync | Named vote-site and automatic site-creation policy presets | Add remaining preset-specific schemas and their exact capability and role checks |
| Proxy routing, fixed proxy YAML, coordinated proxy-method v1/v2 and transport tests | One typed routing read and preview with browser approval, plus a separately granted non-vote transport check | Add fixed proxy YAML projections. Proxy-method changes need the complete reported target set and existing rollback and restart reporting |
| Configuration review, apply, status, retries, durable operation history, snapshots and drift | Token-free, per-target status for operations from the same grant. Browser-only Apply. Automatic site policy supports 1–10 explicit backends with immutable revisions | Extend bounded multi-node review and partial-failure reporting to other safe typed operations |
Expand All @@ -27,7 +27,7 @@ MCP uses an opt-in server boundary, proxy-network grants, bounded discovery and
| Batch site policy | Implemented and tested | Explicit unique targets, separate batch permission, revision per backend, all previews successful before approval, per-target terminal results |
| Typed General Settings | Implemented and tested | Both node roles use the curated editor, scoped reads, exact revision and diff, and browser approval. Proxy applies report restart required |
| Typed Vote Sites editor | Implemented and tested | Exact-site read, typed add/edit, and removal for reviewable sites without inline Rewards. Revision, masked source and leaf changes checked before browser approval |
| Typed Rewards editor | Remaining | Reuse curated reward inventory and safe source-preserving edits without executing rewards |
| Typed Rewards editor | Implemented and tested for supported scalar fields | Inline and named-file reward reads, exact same-scope scalar previews and browser approval. Command payloads and whole-scope edits stay in administrator workflows |
| Remaining guided presets, fixed proxy-file projections, proxy-method changes and VoteSites sync | Remaining | Scope and type each supported request, preserve existing version and role gates, prove rollback and restart outcomes where applicable |
| Other multi-node proposals, typed retries and snapshot or drift projections | Remaining | Add bounded per-target reads, target-specific proposal data and clear validation/partial failure handling |
| Player and vote-log inspections | Separately gated | Require distinct grants and purpose-specific redacted results before exposure |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
import java.util.function.Supplier;

public final class AgentOperations {
private static final Set<String> ACTIONS = Set.of("discover", "read", "preview", "status", "health", "routing", "transport", "site-policy", "site-policy-batch", "general-settings", "vote-sites-editor");
private static final Set<String> ACTIONS = Set.of("discover", "read", "preview", "status", "health", "routing", "transport", "site-policy", "site-policy-batch", "general-settings", "vote-sites-editor", "rewards-editor");
private final Map<UUID, Grant> grants = new HashMap<>();
private final Map<UUID, Instant> healthRefreshes = new HashMap<>();
private final NodeRegistry registry;
Expand Down Expand Up @@ -163,6 +163,24 @@ public synchronized Map<String, Object> refreshHealth(String token, RefreshHealt
}
}

public synchronized Object readReward(String token, RewardRead request) {
Grant grant = authorize(token, "rewards-editor");
return withStableTopology(() -> {
requireNode(grant, request.nodeId());
return project(operations.readAgentReward(grant.id(), request.nodeId(),
AgentSetup.RewardField.select(request.siteKey(), request.rewardName(), request.field())));
});
}

public synchronized Object previewReward(String token, RewardPreview request) {
Grant grant = authorize(token, "rewards-editor");
return withStableTopology(() -> {
requireNode(grant, request.nodeId());
return project(operations.previewAgentReward(grant.id(), request.nodeId(),
parseId(request.readOperationId()), request.value()));
});
}

public synchronized Object readVoteSitesEditor(String token, VoteSitesEditorRead request) {
Grant grant = authorize(token, "vote-sites-editor");
return withStableTopology(() -> {
Expand Down Expand Up @@ -466,6 +484,8 @@ public record Issue(List<String> nodeIds, List<String> actions, Integer minutes,
public record Discovery(Integer offset) { }
public record HealthRequest(List<String> nodeIds) { }
public record RefreshHealth(String nodeId) { }
public record RewardRead(String nodeId, String siteKey, String rewardName, String field) { }
public record RewardPreview(String nodeId, String readOperationId, Object value) { }
public record VoteSitesEditorRead(String nodeId, String siteKey) { }
public record VoteSitesEditorPreview(String nodeId, String siteKey, String readOperationId,
String action, Map<String, Object> fields) { }
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,39 @@ static Map<String, String> editorSiteValues(String key, String document) {
return Map.copyOf(values);
}

record RewardField(String file, String scope, String field) {
static RewardField select(String siteKey, String rewardName, String field) {
if ((siteKey == null) == (rewardName == null) || field == null
|| !field.matches("Money|Chance|Messages[.](Player|Broadcast)|Items[.][A-Za-z0-9_-]{1,64}[.](Material|Amount)")) {
throw new IllegalArgumentException("Select one reward and one supported scalar field");
}
if (siteKey != null && siteKey.matches("[A-Za-z0-9_-]{1,64}")) {
return new RewardField("VoteSites.yml", "VoteSites." + siteKey + ".Rewards", field);
}
if (rewardName != null && rewardName.matches("[A-Za-z0-9][A-Za-z0-9_-]{0,99}")) {
return new RewardField("Rewards/" + rewardName + ".yml", "$", field);
}
throw new IllegalArgumentException("Invalid reward selector");
}

String changePath() {
return "$".equals(scope) ? field : scope + "." + field;
}

Map<String, String> values(String content) {
var selected = RewardsDocument.inventory(content, file).stream()
.filter(row -> scope.equals(row.path())).findFirst().orElseThrow(IllegalArgumentException::new);
if (!selected.editable() || !List.of("PRESENT", "EMPTY").contains(selected.status())) {
throw new IllegalArgumentException("Reward scope is missing or unsupported");
}
Object value = selected.fields().get(field);
if (!(value instanceof String text) || text.length() > 500) {
throw new IllegalArgumentException("Reward field must already be a reviewable scalar");
}
return Map.of("rewardField", field, "rewardValue", text);
}
}

static Map<String, String> settingsValues(Map<String, GeneralSettingsDocument.Field> fields) {
Map<String, String> values = new LinkedHashMap<>();
fields.forEach((key, field) -> {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -300,6 +300,26 @@ synchronized OperationView previewAgentVoteSitesEditor(UUID agent, String nodeId
return createVoteSitesPreview(readId, nodeId, action, siteKey, fields, agent);
}

synchronized OperationView readAgentReward(UUID agent, String nodeId, AgentSetup.RewardField field) {
prune();
requireAgentCapacity(agent);
var selector = ManagedConfiguration.file(field.file(), null);
ValidatedTargets targets = validateTargets(List.of(nodeId), selector.capability());
validateConfigurationTargets(targets, selector);
var read = create("READ", targets, selector, null, Map.of(), agent);
operations.get(read.operationId()).agentRewardField = field;
return read;
}

synchronized OperationView previewAgentReward(UUID agent, String nodeId, UUID readId, Object value) {
prune();
requireAgentCapacity(agent);
var field = agentOperation(agent, readId).agentRewardField;
if (field == null) throw invalid("A typed reward field read is required");
return createRewardsPreview(readId, nodeId, field.file(), field.scope(), "SET_SCALAR",
field.field(), value, agent, field);
}

private void requireAgentCapacity(UUID agent) {
var retained = operations.values().stream().filter(op -> agent.equals(op.agent)).toList();
if (retained.size() >= 48 || retained.stream().filter(op -> !op.complete()).count() >= 4) {
Expand Down Expand Up @@ -629,6 +649,11 @@ public synchronized OperationView createRewardsPreview(UUID readId, String nodeI
String rewardPath, String action, String field, Object value) {
StoredOperation read = operations.get(readId);
if (read != null && read.agent != null) throw invalid("Agent reads require the agent editor");
return createRewardsPreview(readId, nodeId, fileName, rewardPath, action, field, value, null, null);
}

private OperationView createRewardsPreview(UUID readId, String nodeId, String fileName,
String rewardPath, String action, String field, Object value, UUID agent, AgentSetup.RewardField agentField) {
if (!"VoteSites.yml".equals(fileName) && !isNamedRewardFile(fileName))
throw invalid("This reward scope is advanced-only");
ConfigurationTaskResult snapshot = fileSnapshot(readId, nodeId, fileName);
Expand All @@ -645,8 +670,27 @@ public synchronized OperationView createRewardsPreview(UUID readId, String nodeI
validateConfigurationTargets(targets, configuration);
byte[] token = new byte[32];
random.nextBytes(token);
return create("PREVIEW", targets, configuration,
Base64.getUrlEncoder().withoutPadding().encodeToString(token), Map.of(nodeId, snapshot.revision()));
String approval = Base64.getUrlEncoder().withoutPadding().encodeToString(token);
var revisions = Map.of(nodeId, snapshot.revision());
if (agent == null) return create("PREVIEW", targets, configuration, approval, revisions);
String prior;
String next;
try {
prior = agentField.values(snapshot.configuration().content()).get("rewardValue");
next = agentField.values(proposal).get("rewardValue");
} catch (IllegalArgumentException unsupported) {
throw invalid("Reward field cannot be reviewed safely");
}
if (prior.equals(next)) throw invalid("Reward field has no reviewable change");
var preview = create("PREVIEW", targets, configuration, approval, revisions, agent);
var stored = operations.get(preview.operationId());
String path = agentField.changePath();
String label = fileName + " / " + path;
stored.agentBefore = Map.of(label, prior);
stored.agentAfter = Map.of(label, next);
stored.agentDocumentDigest = AgentSetup.documentDigest(snapshot.configuration().content());
stored.agentExpectedChanges = Set.of("changed " + path);
return preview;
}

public record RewardsState(UUID readOperationId, String nodeId, String fileName, UUID sessionId, String revision,
Expand Down Expand Up @@ -1169,6 +1213,11 @@ private OperationView completeCurrentSession(UUID operationId, String nodeId, Co
}
agentRead = AgentSetup.settingsValues(GeneralSettingsDocument.fields(result.configuration().content(),
GeneralSettingsDocument.profileForFile(operation.configuration.fileName())));
} else if (operation.agentRewardField != null) {
if (result.configuration() == null || result.configuration().content() == null) {
throw new IllegalArgumentException("Missing redacted reward source");
}
agentRead = operation.agentRewardField.values(result.configuration().content());
} else if (operation.agentEditorSite != null) {
if (result.configuration() == null || result.configuration().content() == null) {
throw new IllegalArgumentException("Missing redacted VoteSites source");
Expand Down Expand Up @@ -1664,6 +1713,7 @@ private static final class StoredOperation {
private UUID agent;
private String agentSite;
private String agentEditorSite;
private AgentSetup.RewardField agentRewardField;
private boolean agentGeneralSettings;
private String agentDocumentDigest;
private Set<String> agentExpectedChanges = Set.of();
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1137,6 +1137,7 @@ private void routeAgent(HttpExchange exchange, String path) throws IOException {
case "transport" -> "transport";
case "site-policy-read", "site-policy-preview" -> "site-policy";
case "site-policy-batch" -> "site-policy-batch";
case "reward-read", "reward-preview" -> "rewards-editor";
case "vote-sites-editor-read", "vote-sites-editor-preview" -> "vote-sites-editor";
case "settings-read", "settings-preview" -> "general-settings";
case "read", "preview", "status" -> route;
Expand All @@ -1155,6 +1156,8 @@ private void routeAgent(HttpExchange exchange, String path) throws IOException {
case "topology" -> agentOperations.topology(token, read(exchange, AgentOperations.Discovery.class, true));
case "health" -> agentOperations.health(token, read(exchange, AgentOperations.HealthRequest.class, true));
case "health-refresh" -> agentOperations.refreshHealth(token, read(exchange, AgentOperations.RefreshHealth.class, true));
case "reward-read" -> agentOperations.readReward(token, read(exchange, AgentOperations.RewardRead.class, true));
case "reward-preview" -> agentOperations.previewReward(token, read(exchange, AgentOperations.RewardPreview.class, true));
case "vote-sites-editor-read" -> agentOperations.readVoteSitesEditor(token,
read(exchange, AgentOperations.VoteSitesEditorRead.class, true));
case "vote-sites-editor-preview" -> agentOperations.previewVoteSitesEditor(token,
Expand Down
Loading