229 lines
7.5 KiB
Markdown
229 lines
7.5 KiB
Markdown
# MCP Dev Mode Chat Handover — Apr 10, 2026
|
|
|
|
## Why this exists
|
|
|
|
This doc captures important context from the current GPT session because MCP/Gitea access in dev mode does **not** carry memory across chats.
|
|
|
|
Use this file as a fast resume point for future sessions.
|
|
|
|
---
|
|
|
|
## What was reviewed across repos
|
|
|
|
### Repos reviewed
|
|
- `zlh-grind`
|
|
- `knowledge-base`
|
|
- `zlh-agent`
|
|
- `zpack-api`
|
|
- `zpack-portal`
|
|
- `ZpackVelocityBridge`
|
|
|
|
### Trust order established
|
|
1. `knowledge-base` for canonical architecture
|
|
2. `zlh-grind` for current execution state / handover
|
|
3. source repos for implementation truth
|
|
4. older docs/logs only when needed
|
|
|
|
Important nuance:
|
|
- `INFRASTRUCTURE.md` had been overwritten/truncated and was restored during this session.
|
|
|
|
---
|
|
|
|
## Infrastructure doc recovery completed
|
|
|
|
### What happened
|
|
- `zlh-grind/INFRASTRUCTURE.md` had been overwritten down to a single PBS row.
|
|
- History was checked and the earlier full infrastructure version was recovered from Git history.
|
|
- The current surviving PBS row data was preserved and merged into the restored file.
|
|
|
|
### Recovery actions completed
|
|
- Restored full infra doc structure
|
|
- Preserved `9017 zlh-back` current data:
|
|
- `10.60.0.24`
|
|
- `172.60.0.30`
|
|
- Corrected router WAN IPs:
|
|
- `9001 zlh-router` → `66.163.115.221`
|
|
- `9002 zpack-router` → `66.163.115.115`
|
|
- Removed obsolete `internal.zlh` inventory section
|
|
- Replaced that with a note that `internal.zlh` is not used for current hot-path service discovery
|
|
|
|
### Current status
|
|
- `INFRASTRUCTURE.md` is usable again as a working infra reference
|
|
- It should still get a quick sanity pass if any other VM/IP rows changed after Apr 2, 2026
|
|
|
|
---
|
|
|
|
## Cross-repo architecture understanding established
|
|
|
|
### Confirmed architecture
|
|
- Portal → API → Agent
|
|
- Hosted IDE access is API-mediated
|
|
- Console access is API websocket bridge mediated
|
|
- Agent owns runtime/filesystem execution
|
|
- Velocity consumes platform state sourced through the API / plugin path
|
|
|
|
### Repo-specific conclusions
|
|
|
|
#### `zpack-api`
|
|
Confirmed in source:
|
|
- hosted IDE flow is implemented in `src/routes/devProxy.js`
|
|
- console proxy is implemented in `src/routes/consoleProxy.js`
|
|
- internal Velocity server-list endpoint is implemented in `src/routes/internalVelocity.js`
|
|
- game/server lifecycle orchestration is handled through API routes like `servers.js`
|
|
|
|
#### `zpack-portal`
|
|
Confirmed in source:
|
|
- Open IDE uses the newer API-mediated flow (`POST /api/dev/:vmid/ide-token`)
|
|
- Console uses the API websocket bridge path
|
|
- Portal still has some migration debt via `src/lib/api/legacy.ts`
|
|
- `testdameon`/`testdaemon` style cleanup debt had been noted earlier in review
|
|
|
|
#### `zlh-agent`
|
|
Confirmed in source:
|
|
- real Minecraft readiness probing exists in `internal/minecraft/readiness.go`
|
|
- agent has Fabric-specific provisioning support
|
|
- likely unresolved issue is sequencing/use of readiness, not total lack of Fabric support
|
|
|
|
---
|
|
|
|
## Important correction on Velocity / registration model
|
|
|
|
Earlier working assumption was that the API might directly push registration into Velocity.
|
|
|
|
After code review, the more accurate model is:
|
|
- API exposes server inventory/state
|
|
- Velocity plugin consumes that information and performs actual server registration inside Velocity
|
|
|
|
So the plugin is a key part of the registration/readiness path.
|
|
|
|
---
|
|
|
|
## `ZpackVelocityBridge` review summary
|
|
|
|
### Repo hygiene
|
|
- Repo was initially pushed with generated Gradle junk (`.gradle/`, `build/`)
|
|
- User deleted and recreated repo
|
|
- Cleaner push landed afterward
|
|
- Current repo is clean of generated build junk
|
|
- Remaining mild annoyance: extra top-level folder `ZpackVelocityBridge/` still exists
|
|
- This nesting is not a blocker, just mildly inconvenient
|
|
|
|
### Key plugin findings
|
|
|
|
#### 1. The plugin does actual Velocity registration
|
|
`ServerRegistry.java` performs:
|
|
- `proxy.registerServer(...)`
|
|
- `proxy.unregisterServer(...)`
|
|
|
|
So plugin code is the component actually adding/removing backends in Velocity.
|
|
|
|
#### 2. The plugin startup flow pulls from API
|
|
In `ZpackVelocityBridge.java`, startup rehydrate pulls backend inventory from the API.
|
|
|
|
Important detail found during review:
|
|
- the default endpoint still points to `zpack-api.internal.zlh`
|
|
- that default is stale relative to the current architecture unless overridden externally
|
|
|
|
#### 3. The plugin likely ignores readiness during startup rehydrate
|
|
Most important finding from plugin review:
|
|
- plugin startup rehydrate appears to register servers returned by the API
|
|
- it does **not** appear to require `ready == true` before registration
|
|
|
|
This is likely the core explanation for Fabric being surfaced too early.
|
|
|
|
Better phrasing of the bug:
|
|
- API/plugin path is exposing/registering a backend while the Minecraft/Fabric server is `running` but not actually `ready`
|
|
|
|
#### 4. Plugin also exposes webhook-style HTTP endpoints
|
|
From `ZpackHttpHandlers.java`:
|
|
- `POST /zpack/register`
|
|
- `POST /zpack/unregister`
|
|
- `GET /zpack/status`
|
|
|
|
So plugin supports both:
|
|
- startup/API rehydrate
|
|
- webhook-style live register/unregister
|
|
|
|
Needs future verification:
|
|
- is anything actually calling these webhook endpoints in production now?
|
|
- or is plugin state mostly startup snapshot + manual restarts?
|
|
|
|
#### 5. Routing layer is simple and not the bug
|
|
`RoutingHandler.java` does:
|
|
- hostname exact match first
|
|
- single-server fallback when only one backend exists
|
|
- otherwise deny
|
|
|
|
Routing is consuming registry state, not deciding readiness.
|
|
|
|
---
|
|
|
|
## Most likely active technical issue now
|
|
|
|
### Best current diagnosis
|
|
The most likely active Minecraft/Fabric issue is:
|
|
|
|
> The API/plugin path is allowing a backend to be registered in Velocity when the server is `running` but not actually `ready`.
|
|
|
|
This is more precise than the earlier broader theory about generic Fabric artifact mismatch.
|
|
|
|
### Highest-value next code change
|
|
Patch `ZpackVelocityBridge` so startup rehydrate only registers servers where:
|
|
- `ready == true`
|
|
|
|
Not merely:
|
|
- valid name/address/port
|
|
- `status=running`
|
|
|
|
### Second plugin follow-up
|
|
Replace or remove stale default reliance on:
|
|
- `zpack-api.internal.zlh`
|
|
|
|
Use current configured API address / env-configured endpoint instead.
|
|
|
|
---
|
|
|
|
## Current repo / session state at end of this chat
|
|
|
|
### Completed
|
|
- multi-repo review completed
|
|
- trust order established
|
|
- `INFRASTRUCTURE.md` restored and corrected
|
|
- plugin repo reviewed
|
|
- plugin repo cleaned of generated junk after recreate/re-push
|
|
|
|
### Still open
|
|
- patch plugin startup rehydrate to honor `ready`
|
|
- confirm whether plugin webhook endpoints are actively used
|
|
- optionally flatten `ZpackVelocityBridge` repo so project files live at repo root
|
|
- optionally reduce Portal dependency on `legacy.ts`
|
|
- validate remaining infra rows for any post-Apr-2 changes
|
|
|
|
---
|
|
|
|
## Recommended next move for future chat
|
|
|
|
### First recommended task
|
|
Patch `ZpackVelocityBridge`:
|
|
1. inspect startup rehydrate logic in `ZpackVelocityBridge.java`
|
|
2. require `ready == true` before `registerIfAbsent(...)`
|
|
3. review stale default API endpoint behavior (`internal.zlh` default)
|
|
4. decide whether webhook mode, polling, or startup-only rehydrate is the intended long-term model
|
|
|
|
### Secondary follow-up
|
|
After patching plugin:
|
|
- retest Fabric readiness / Velocity exposure sequence
|
|
- verify Fabric backend is not routable until actually accepting connections
|
|
|
|
---
|
|
|
|
## Notes for future GPT session
|
|
|
|
Do not restart broad repo discovery from scratch.
|
|
|
|
Resume from these assumptions unless newer code disproves them:
|
|
- architecture understanding is already established
|
|
- infra doc recovery is complete
|
|
- plugin is the registration actor inside Velocity
|
|
- plugin readiness handling is the most likely near-term bug
|