guillaumearm/cc-libs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: delete old trap-sandbox/INIT.md (now we have proper spec and plans)

Browse Source
This commit is contained in:
Guillaume ARM 2026-06-14 03:46:44 +02:00
parent 09a409c179
commit a8485a780f
1 changed files with 0 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
tools/trap-sandbox/INIT.md
View File

@ -1,73 +0,0 @@
# INIT PLAN
## Goal
The goal of trap-sandbox will be a general purpose api for several of my experiences, for now we will simply add:
- a websocket server to let a craftos computer communicate with opencode (and vice-versa)
- Warning: here we should take care of a request/reply mechanism (with quite long timeout like 600s by default could be nice)
- Bi-directional means the sandbox can make a request to a computer and get a reply but the inverse is also possible (computer requesting the sandbox) so we will keep in mind that we are in an async world so we work with events and we will have 4 events here (2 requests and 2 responses events)
## First iteration
Here we will try to get straight to the point in term of code, the goal is to make it work. (We will refactor later)
There is basically 2 things we need to focus on:
1. the `trapos-cloud-gateway` sandbox module.
2. a `trapos-sandbox.lua` that will be able to communicate with the trapos gateway
### the trapos-cloud-gateway module
Here the 4 events we have to handle are generic events.
a unique trapos identifier (that will be id+label for now because this gateway could handle several computers across several minecraft servers for example) will be needed in the payload of all events emitted by a trapos computer -> Warning: One ws connection = 1 trapos identifier, if there is a duplicate computer the websocket connection should be rejected by the gateway.
every message should have a unique "messageId" (by trapos identifier at least)
this messageId will be useful to get the response later.
The messages are generic and are just a {type, payload} structure (ala redux) so next to type/payload you will find traposSenderId and messageId, no `meta` property here -> so {traposSenderId, messsageId, type, payload}
The interpretation of the message will be up to the trapos-sandbox. (when request are sent to a trapos computer)
We will add later a way to link trapos-cloud-gateway to other "modules" (or maybe another concept here to avoid cross-module interaction and keep it decoupled)
For now the only feature is a `{ type: "health", payload: { sandboxOk: boolean, opencodeOk: boolean } }` or something like that (maybe more details in the payload could be nice)
So a trapos computer could ask to the gateway his health (this is the first use-case to verify a computer is connected to the "trapos sandbox")
To make the difference between a sent message and a received message (if needed) we can consider having a `traposReceiverId` that is supposed to carry the traposId of the computer that will receive a new message from the gateway.
I will let you propose something for the shape of our 4 events (let's decide in the typescript part first)
### sandbox.lua
This one will be in `servers/sandbox.lua` and will be installed by `trapos-sandbox` package.
This server will interface with the 4 generic communication events. it will transform websocket received events in trapos events (check eventloop.lua to be sure everything will be well integrated)
It will also forward websocket events if a computer want to communicate with the gateway (for example asking the health)
### Technical Requirements
- The trap-sandbox server default port will be 4444
- trap-sandbox will be separated in several "sandbox modules" that are basically fastify routers and/or middlewares. -> here we have one module that is the cloud gateway for trapos
- integration tests with craftos need to be wrote.
- code in typescript
- use @opencode-ai/sdk (use context7 mcp if available when you need to read the doc)
- use typescript-eslint (add npm run lint)
- Keep the basic password mechanism we put in place previously (apis/libhttp.lua and tools/mcp-bridge)
## Final outcome
I should be able in-game after installing new version of trapos to use `sandbox health` command to get the health of the gateway and opencode server
## Out of scope for this plan
full integration with opencode-server (outside of the /health route)
## Other notes
Another important thing to take care about -> Today this `tools/trap-sandbox` project is not the same as 'trapos-sandbox' that should be considered as legacy now. so we will rename the package "trapos-sandbox" in "trapos-sanbox-legacy" and we will create trapos-sandbox that will take care of the link with trap-sandbox
btw all of this is about replacing (from scratch) ../../tools/mcp-bridge/ that should be considered legacy now, you can take a look if you need inspiration (but not too much, if I restarted from scratch it's because I don't like the actual direction, so if something is missing, don't hesitate to ask) -> but for integration tests inspiration it's still interesting to watch.
At some point we will rewrite ai.lua but it's not part of this plan (and we don't care if we break it, I'm the only user of trapos for now so we can breaking change if we can make the code better)