feat: add entity listing/goto workflow updates and bridge end command

Author: GSstarGamer

AGENTS.md

@@ -0,0 +1,23 @@
+# Repository Agent Rules
+
+## Chat Context Maintenance (Required)
+For every meaningful task in this repository:
+1. Append an entry to `chat-context/UPDATES.md`.
+2. Include:
+   - date
+   - short request summary
+   - what changed (files/APIs/behavior)
+   - validation commands run
+   - notable follow-up note/risk (if any)
+
+## When To Also Update `chat-context/README.md`
+Update `chat-context/README.md` if the task changes:
+1. architecture or protocol surface,
+2. public API shape/usage guidance,
+3. key operational workflows (start/stop/debug behavior),
+4. important project-orientation context future chats should know first.
+
+## Startup Read Order
+1. `chat-context/README.md`
+2. `chat-context/UPDATES.md`
+3. Then proceed to task-specific files.

mod/src/main/java/com/pyritone/bridge/PyritoneBridgeClientMod.java

@@ -1,6 +1,7 @@
 package com.pyritone.bridge;
 
 import com.google.gson.JsonElement;
+import com.google.gson.JsonArray;
 import com.google.gson.JsonObject;
 import com.pyritone.bridge.command.PyritoneCommand;
 import com.pyritone.bridge.config.BridgeConfig;
@@ -9,6 +10,7 @@
 import com.pyritone.bridge.net.ProtocolCodec;
 import com.pyritone.bridge.net.WebSocketBridgeServer;
 import com.pyritone.bridge.runtime.BaritoneGateway;
+import com.pyritone.bridge.runtime.EntityTypeSelector;
 import com.pyritone.bridge.runtime.StatusSubscriptionRegistry;
 import com.pyritone.bridge.runtime.TaskRegistry;
 import com.pyritone.bridge.runtime.TaskLifecycleResolver;
@@ -22,6 +24,8 @@
 import net.fabricmc.fabric.api.client.message.v1.ClientSendMessageEvents;
 import net.fabricmc.loader.api.FabricLoader;
 import net.minecraft.client.MinecraftClient;
+import net.minecraft.entity.Entity;
+import net.minecraft.registry.Registries;
 import net.minecraft.text.MutableText;
 import net.minecraft.text.Text;
 import net.minecraft.util.Formatting;
@@ -35,7 +39,10 @@
 import java.nio.file.StandardOpenOption;
 import java.security.MessageDigest;
 import java.time.Instant;
+import java.util.ArrayList;
+import java.util.Comparator;
 import java.util.List;
+import java.util.Locale;
 import java.util.Optional;
 import java.util.Set;
 import java.util.concurrent.CompletionException;
@@ -76,7 +83,7 @@ public void onInitializeClient() {
 
         ClientTickEvents.END_CLIENT_TICK.register(client -> {
             baritoneGateway.tickRegisterPathListener();
-            baritoneGateway.tickRegisterPyritoneHashCommand(this::forceCancelActiveTaskFromPyritoneCommand);
+            baritoneGateway.tickRegisterPyritoneHashCommand(() -> endPythonSessionsFromPyritoneCommand());
             baritoneGateway.tickApplyPyritoneChatBranding();
             tickTaskLifecycle();
             tickStatusStreams();
@@ -132,8 +139,8 @@ private void ensureBaritoneSettingsFile() {
         }
     }
     private boolean handleOutgoingChat(String message) {
-        if (message != null && message.trim().equalsIgnoreCase("#pyritone cancel")) {
-            forceCancelActiveTaskFromPyritoneCommand();
+        if (message != null && message.trim().equalsIgnoreCase("#pyritone end")) {
+            endPythonSessionsFromPyritoneCommand();
             return false;
         }
         emitWatchMatches("chat", message);
@@ -216,6 +223,7 @@ private JsonObject handleRequest(WebSocketBridgeServer.ClientSession session, Js
                 case "api.metadata.get" -> handleApiMetadataGet(id, params, session);
                 case "api.construct" -> handleApiConstruct(id, params, session);
                 case "api.invoke" -> handleApiInvoke(id, params, session);
+                case "entities.list" -> handleEntitiesList(id, params);
                 case "baritone.execute" -> handleBaritoneExecute(id, params);
                 case "task.cancel" -> handleTaskCancel(id);
                 default -> ProtocolCodec.errorResponse(id, "METHOD_NOT_FOUND", "Unknown method: " + method);
@@ -304,6 +312,62 @@ private JsonObject handleApiInvoke(String id, JsonObject params, WebSocketBridge
         return handleTypedApiRequest(id, () -> typedApiService.invoke(session.sessionId(), params));
     }
 
+    private JsonObject handleEntitiesList(String id, JsonObject params) {
+        try {
+            JsonObject result = runOnClientThread(() -> {
+                MinecraftClient client = MinecraftClient.getInstance();
+                if (client == null || client.world == null || client.player == null) {
+                    throw new TypedApiException("NOT_IN_WORLD", "Join a world before listing entities");
+                }
+
+                EntityTypeSelector selector = EntityTypeSelector.fromParams(params);
+
+                List<JsonObject> entities = new ArrayList<>();
+                for (Entity entity : client.world.getEntities()) {
+                    if (entity == client.player) {
+                        continue;
+                    }
+
+                    String typeId = Registries.ENTITY_TYPE.getId(entity.getType()).toString();
+                    if (!selector.matches(entity, typeId)) {
+                        continue;
+                    }
+
+                    JsonObject payload = new JsonObject();
+                    payload.addProperty("id", entity.getUuidAsString());
+                    payload.addProperty("type_id", typeId);
+                    payload.addProperty("category", entity.getType().getSpawnGroup().name().toLowerCase(Locale.ROOT));
+                    payload.addProperty("x", entity.getX());
+                    payload.addProperty("y", entity.getY());
+                    payload.addProperty("z", entity.getZ());
+                    payload.addProperty("distance_sq", client.player.squaredDistanceTo(entity));
+                    entities.add(payload);
+                }
+
+                entities.sort(Comparator.comparingDouble(entity -> entity.get("distance_sq").getAsDouble()));
+
+                JsonArray entries = new JsonArray();
+                for (JsonObject entity : entities) {
+                    entries.add(entity);
+                }
+
+                JsonObject response = new JsonObject();
+                response.add("entities", entries);
+                return response;
+            });
+            return ProtocolCodec.successResponse(id, result);
+        } catch (IllegalArgumentException exception) {
+            return ProtocolCodec.errorResponse(id, "BAD_REQUEST", exception.getMessage());
+        } catch (TypedApiException exception) {
+            return ProtocolCodec.errorResponse(id, exception.code(), exception.getMessage(), exception.details());
+        } catch (TimeoutException exception) {
+            return ProtocolCodec.errorResponse(id, "INTERNAL_ERROR", "Timed out waiting for client thread");
+        } catch (Exception exception) {
+            LOGGER.debug("entities.list request failed", exception);
+            return ProtocolCodec.errorResponse(id, "INTERNAL_ERROR", "Unable to list entities");
+        }
+    }
+
     private JsonObject buildStatusPayload(WebSocketBridgeServer.ClientSession session) {
         JsonObject result = new JsonObject();
         result.addProperty("protocol_version", BridgeConfig.PROTOCOL_VERSION);
@@ -328,7 +392,9 @@ private JsonObject handleBaritoneExecute(String id, JsonObject params) {
             return ProtocolCodec.errorResponse(id, "BAD_REQUEST", "Missing command");
         }
 
-        emitPyritoneNotice("Python execute: " + compactCommand(command));
+        String label = asString(params, "label");
+        String notice = label != null && !label.isBlank() ? label : command;
+        emitPyritoneNotice("Python execute: " + compactCommand(notice));
 
         if (!baritoneGateway.isAvailable()) {
             emitPyritoneNotice("Python execute blocked: Baritone unavailable");
@@ -447,6 +513,31 @@ private Object resolvePrimaryBaritone() throws ReflectiveOperationException {
         return baritoneGateway.resolvePrimaryBaritoneForTypedApi();
     }
 
+    public int endPythonSessionsFromPyritoneCommand() {
+        WebSocketBridgeServer currentServer = this.server;
+        if (currentServer == null || !currentServer.isRunning()) {
+            emitPyritoneNotice("Bridge is not running");
+            return 0;
+        }
+
+        int disconnected = 0;
+        for (WebSocketBridgeServer.ClientSession session : currentServer.sessionSnapshot()) {
+            if (!session.isAuthenticated()) {
+                continue;
+            }
+            session.close();
+            disconnected += 1;
+        }
+
+        if (disconnected > 0) {
+            emitPyritoneNotice("Ended " + disconnected + " Python websocket session(s)");
+        } else {
+            emitPyritoneNotice("No authenticated Python websocket sessions");
+        }
+
+        return disconnected;
+    }
+
     public boolean forceCancelActiveTaskFromPyritoneCommand() {
         Optional<TaskSnapshot> active = taskRegistry.active();
         if (active.isEmpty()) {

mod/src/main/java/com/pyritone/bridge/command/PyritoneCommand.java

@@ -19,13 +19,13 @@ public static void register(PyritoneBridgeClientMod mod) {
                             context.getSource().sendFeedback(Text.literal(mod.commandStatusLine()));
                             return 1;
                         }))
-                    .then(ClientCommandManager.literal("cancel")
+                    .then(ClientCommandManager.literal("end")
                         .executes(context -> {
-                            boolean canceled = mod.forceCancelActiveTaskFromPyritoneCommand();
-                            if (canceled) {
-                                context.getSource().sendFeedback(Text.literal("Requested hard cancel for active Py-Ritone task"));
+                            int disconnected = mod.endPythonSessionsFromPyritoneCommand();
+                            if (disconnected > 0) {
+                                context.getSource().sendFeedback(Text.literal("Ended " + disconnected + " Python websocket session(s)"));
                             } else {
-                                context.getSource().sendFeedback(Text.literal("No active Py-Ritone task"));
+                                context.getSource().sendFeedback(Text.literal("No authenticated Python websocket sessions"));
                             }
                             return 1;
                         }))

mod/src/main/java/com/pyritone/bridge/runtime/BaritoneGateway.java

@@ -62,9 +62,9 @@ public void tickRegisterPathListener() {
         }, false);
     }
 
-    public void tickRegisterPyritoneHashCommand(Runnable cancelAction) {
+    public void tickRegisterPyritoneHashCommand(Runnable endAction) {
         onClientThread(() -> {
-            ensurePyritoneHashCommandOnClientThread(cancelAction);
+            ensurePyritoneHashCommandOnClientThread(endAction);
             return true;
         }, false);
     }
@@ -151,8 +151,8 @@ private void ensurePathListenerOnClientThread() {
         }
     }
 
-    private void ensurePyritoneHashCommandOnClientThread(Runnable cancelAction) {
-        if (cancelAction == null) {
+    private void ensurePyritoneHashCommandOnClientThread(Runnable endAction) {
+        if (endAction == null) {
             return;
         }
 
@@ -181,7 +181,7 @@ private void ensurePyritoneHashCommandOnClientThread(Runnable cancelAction) {
 
             ClassLoader loader = getClass().getClassLoader();
             Class<?> iCommand = Class.forName("baritone.api.command.ICommand", true, loader);
-            InvocationHandler handler = (proxy, method, args) -> handlePyritoneCommandCall(proxy, method, args, cancelAction);
+            InvocationHandler handler = (proxy, method, args) -> handlePyritoneCommandCall(proxy, method, args, endAction);
             Object commandProxy = Proxy.newProxyInstance(loader, new Class<?>[]{iCommand}, handler);
 
             Object registered = invoke(registry, "register", new Class<?>[]{Object.class}, new Object[]{commandProxy});
@@ -395,30 +395,30 @@ private Object handleEventListenerCall(Object proxy, Method method, Object[] arg
         return defaultValue(method.getReturnType());
     }
 
-    private Object handlePyritoneCommandCall(Object proxy, Method method, Object[] args, Runnable cancelAction) {
+    private Object handlePyritoneCommandCall(Object proxy, Method method, Object[] args, Runnable endAction) {
         String methodName = method.getName();
         switch (methodName) {
             case "execute" -> {
                 String subcommand = extractFirstArg(args);
-                if ("cancel".equals(subcommand)) {
-                    cancelAction.run();
+                if ("end".equals(subcommand)) {
+                    endAction.run();
                 }
                 return null;
             }
             case "tabComplete" -> {
                 String prefix = extractFirstArg(args);
                 if (prefix.isBlank()) {
-                    return Stream.of("cancel");
+                    return Stream.of("end");
                 }
-                return Stream.of("cancel").filter(option -> option.startsWith(prefix));
+                return Stream.of("end").filter(option -> option.startsWith(prefix));
             }
             case "getShortDesc" -> {
                 return "Py-Ritone controls";
             }
             case "getLongDesc" -> {
                 return List.of(
                     "Py-Ritone command bridge",
-                    "Usage: #pyritone cancel"
+                    "Usage: #pyritone end"
                 );
             }
             case "getNames" -> {

mod/src/main/java/com/pyritone/bridge/runtime/EntityTypeSelector.java

@@ -0,0 +1,114 @@
+package com.pyritone.bridge.runtime;
+
+import com.google.gson.JsonArray;
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import net.minecraft.entity.Entity;
+import net.minecraft.entity.mob.MobEntity;
+import net.minecraft.entity.player.PlayerEntity;
+
+import java.util.HashSet;
+import java.util.Objects;
+import java.util.Set;
+import java.util.regex.Pattern;
+
+public final class EntityTypeSelector {
+    public static final String GROUP_PLAYERS = "group:players";
+    public static final String GROUP_MOBS = "group:mobs";
+
+    private static final Pattern ENTITY_ID_PATTERN = Pattern.compile("^[a-z0-9_.-]+:[a-z0-9_./-]+$");
+
+    private final boolean includePlayers;
+    private final boolean includeMobs;
+    private final Set<String> explicitTypeIds;
+
+    private EntityTypeSelector(boolean includePlayers, boolean includeMobs, Set<String> explicitTypeIds) {
+        this.includePlayers = includePlayers;
+        this.includeMobs = includeMobs;
+        this.explicitTypeIds = Set.copyOf(explicitTypeIds);
+    }
+
+    public static EntityTypeSelector fromParams(JsonObject params) {
+        if (params == null || !params.has("types") || params.get("types").isJsonNull()) {
+            return allowAll();
+        }
+
+        JsonElement typesElement = params.get("types");
+        if (!typesElement.isJsonArray()) {
+            throw new IllegalArgumentException("entities.list params.types must be an array of strings");
+        }
+
+        JsonArray typeArray = typesElement.getAsJsonArray();
+        boolean includePlayers = false;
+        boolean includeMobs = false;
+        Set<String> explicitTypeIds = new HashSet<>();
+
+        for (int index = 0; index < typeArray.size(); index += 1) {
+            JsonElement entry = typeArray.get(index);
+            if (!entry.isJsonPrimitive() || !entry.getAsJsonPrimitive().isString()) {
+                throw new IllegalArgumentException("entities.list params.types entries must be strings");
+            }
+
+            String rawValue = entry.getAsString();
+            String value = rawValue == null ? "" : rawValue.trim();
+            if (value.isEmpty()) {
+                throw new IllegalArgumentException("entities.list params.types entries must be non-empty strings");
+            }
+
+            if (value.startsWith("group:")) {
+                switch (value) {
+                    case GROUP_PLAYERS -> includePlayers = true;
+                    case GROUP_MOBS -> includeMobs = true;
+                    default -> throw new IllegalArgumentException(
+                        "Unknown entities.list group token: "
+                            + value
+                            + " (supported: "
+                            + GROUP_PLAYERS
+                            + ", "
+                            + GROUP_MOBS
+                            + ")"
+                    );
+                }
+                continue;
+            }
+
+            if (!ENTITY_ID_PATTERN.matcher(value).matches()) {
+                throw new IllegalArgumentException(
+                    "Invalid entities.list types entry at index "
+                        + index
+                        + ": expected entity id (namespace:path) or group token"
+                );
+            }
+
+            explicitTypeIds.add(value);
+        }
+
+        return new EntityTypeSelector(includePlayers, includeMobs, explicitTypeIds);
+    }
+
+    public boolean matches(Entity entity, String typeId) {
+        Objects.requireNonNull(entity, "entity");
+        return matches(typeId, entity instanceof PlayerEntity, entity instanceof MobEntity);
+    }
+
+    boolean matches(String typeId, boolean isPlayer, boolean isMob) {
+        if (!hasFilters()) {
+            return true;
+        }
+        if (includePlayers && isPlayer) {
+            return true;
+        }
+        if (includeMobs && isMob) {
+            return true;
+        }
+        return typeId != null && explicitTypeIds.contains(typeId);
+    }
+
+    private boolean hasFilters() {
+        return includePlayers || includeMobs || !explicitTypeIds.isEmpty();
+    }
+
+    private static EntityTypeSelector allowAll() {
+        return new EntityTypeSelector(false, false, Set.of());
+    }
+}