golem-bridge 3.0.1 → 3.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +107 -94
  2. package/cli.js +1237 -1109
  3. package/golem-tools.md +702 -694
  4. package/package.json +4 -1
package/README.md CHANGED
@@ -1,94 +1,107 @@
1
- # Golem
2
-
3
- `golem-bridge` connects an AI coding agent to a live Roblox Studio session
4
- running the Golem plugin.
5
-
6
- This repo holds the npm package (the AI side). The Studio plugin itself is
7
- distributed through the Roblox Creator Store; its source is published as
8
- a file release on this repo's Releases page.
9
-
10
- ## How it connects
11
-
12
- The plugin shows one line in Studio (popup on every start, also in Settings):
13
-
14
- ```
15
- Connect to my Roblox Studio, Run: npx golem-bridge connect <channelId>
16
- ```
17
-
18
- The line is a session token: Studio mints a fresh channel on every start
19
- and wipes the old one.
20
-
21
- Best flow: the user runs the line themselves, so the secret never enters
22
- AI chat, then tells the AI it is connected. Or the user sends the line to
23
- their AI and it runs it. Either way:
24
-
25
- ```sh
26
- npx golem-bridge connect <channelId>
27
- ```
28
-
29
- verifies Studio is alive, saves the 16-char channel to `./.golem/channel`,
30
- and prints the tool manual. Nothing else is installed: every command runs
31
- straight from this package:
32
-
33
- ```sh
34
- npx golem-bridge ping
35
- npx golem-bridge tree --depth 3
36
- ```
37
-
38
- `ping` should return `"ok": true` plus the open place name. `manual`
39
- reprints the reference any time (`help <tool>` explains one tool).
40
-
41
- After a Studio restart, relink with the new line:
42
-
43
- ```sh
44
- npx golem-bridge reconnect <newChannelId>
45
- ```
46
-
47
- Done with a session? Forget it locally (Studio is unaffected):
48
-
49
- ```sh
50
- npx golem-bridge disconnect
51
- ```
52
-
53
- ## Files
54
-
55
- - `cli.js` - the whole package: session setup plus every Studio tool
56
- - `golem-tools.md` - the agent manual (printed by `connect` and `manual`)
57
- - `package.json` - npm manifest
58
-
59
- ## Notes
60
-
61
- - Relay: `https://roblox-golem-default-rtdb.firebaseio.com/`. The channel id
62
- is the secret. Studio mints a fresh one on every start and wipes the old
63
- channel, so a leaked line dies with the session.
64
- - Only `cli.js` and `golem-tools.md` ship in this package. The relay carries
65
- small JSON commands and results only, and `connect` writes nothing but
66
- the 16-char channel id.
67
- - npm account `skellzy` and GitHub `nickils` are the same person.
68
-
69
- - Leaked a line mid-session? Settings > END SESSION AND ROTATE CHANNEL
70
- in the plugin kills it on the spot and issues a new one. (Every Studio
71
- restart already rotates automatically.)
72
-
73
- ## Security
74
-
75
- Trust model: whoever holds the channel ID can send commands to that Studio
76
- session and read the results. Treat the setup line like a password. It
77
- expires on every Studio restart.
78
-
79
- - `connect` verifies Studio is alive over HTTPS, saves the channel id,
80
- and prints the manual. Read both files here before running anything, or
81
- pass `--print` to verify without saving.
82
- - `connect` only accepts hex channel IDs, talks HTTPS to the relay only
83
- (never follows redirects), times out stalled requests, and caps response
84
- sizes. The only data it acts on is a small `ping` reply.
85
- - There are no baked-in Firebase credentials or signing keys: the channel
86
- ID itself is the capability, and transport runs over HTTPS. Public client
87
- code cannot hold a secret, so any "signed responses" scheme here would be
88
- theater rather than security.
89
- - Socket.dev flags the "URL strings" in this package (the relay address).
90
- That is informational: the relay address is the product.
91
- - Scanners also flag the Lua execution and editing commands. That is
92
- what Golem is: your agent driving your own Studio. The session key
93
- (16 hex chars, rotated every start, revocable in one click) is the
94
- whole security model.
1
+ # Golem
2
+
3
+ `golem-bridge` connects an AI coding agent to a live Roblox Studio session
4
+ running the Golem plugin.
5
+
6
+ This repo holds the npm package (the AI side) and the Studio plugin source
7
+ (`plugin/Golem.lua`). The built plugin (`plugin/Golem.rbxmx`) is attached
8
+ to each GitHub Release and distributed through the Roblox Creator Store.
9
+
10
+ ## How it connects
11
+
12
+ The plugin shows one line in Studio (popup on every start, also in Settings):
13
+
14
+ ```
15
+ Connect to my Roblox Studio, Run: npx golem-bridge connect <channelId>
16
+ ```
17
+
18
+ The line is a session token: Studio mints a fresh channel on every start
19
+ and wipes the old one.
20
+
21
+ Best flow: the user runs the line themselves, so the secret never enters
22
+ AI chat, then tells the AI it is connected. Or the user sends the line to
23
+ their AI and it runs it. Either way:
24
+
25
+ ```sh
26
+ npx golem-bridge connect <channelId>
27
+ ```
28
+
29
+ verifies Studio is alive, saves the 16-char channel to `./.golem/channel`,
30
+ and prints the tool manual. Nothing else is installed: every command runs
31
+ straight from this package:
32
+
33
+ ```sh
34
+ npx golem-bridge ping
35
+ npx golem-bridge tree --depth 3
36
+ ```
37
+
38
+ `ping` should return `"ok": true` plus the open place name. `manual`
39
+ reprints the reference any time (`help <tool>` explains one tool).
40
+
41
+ After a Studio restart, relink with the new line:
42
+
43
+ ```sh
44
+ npx golem-bridge reconnect <newChannelId>
45
+ ```
46
+
47
+ Done with a session? Forget it locally (Studio is unaffected):
48
+
49
+ ```sh
50
+ npx golem-bridge disconnect
51
+ ```
52
+
53
+ ## Files
54
+
55
+ - `cli.js` - the whole package: session setup plus every Studio tool
56
+ - `golem-tools.md` - the agent manual (printed by `connect` and `manual`)
57
+ - `package.json` - npm manifest
58
+
59
+ ## Notes
60
+
61
+ - Relay: `https://roblox-golem-default-rtdb.firebaseio.com/`. The channel id
62
+ is the secret. Studio mints a fresh one on every start and wipes the old
63
+ channel, so a leaked line dies with the session.
64
+ - Only `cli.js` and `golem-tools.md` ship as code in this package (npm
65
+ always adds `README.md`, `LICENSE`, and `package.json` alongside). The
66
+ relay carries small JSON commands and results only, and `connect` writes
67
+ nothing but the channel id (mode `0600`, since it is a secret).
68
+ - npm account `skellzy` and GitHub `nickils` are the same person.
69
+
70
+ - Leaked a line mid-session? Settings > END SESSION AND ROTATE CHANNEL
71
+ in the plugin kills it on the spot and issues a new one. (Every Studio
72
+ restart already rotates automatically.)
73
+
74
+ ## Environment variables (all optional)
75
+
76
+ `GOLEM_*` names are preferred; the `AIB_*` aliases still work.
77
+
78
+ - `GOLEM_CHANNEL` (`AIB_CHANNEL`) — use this channel instead of
79
+ `./.golem/channel`. When set, `connect`/`reconnect` warn that the saved
80
+ file is shadowed, and `disconnect` warns the session stays connected.
81
+ - `GOLEM_FIREBASE_DB` (`AIB_FIREBASE_DB`) — relay base URL override.
82
+ Must be HTTPS, except `http://localhost…` for emulator testing.
83
+ - `GOLEM_POLL_INTERVAL` (`AIB_POLL_INTERVAL`) — result poll interval in
84
+ seconds (default 2, minimum 0.25).
85
+
86
+ ## Security
87
+
88
+ Trust model: whoever holds the channel ID can send commands to that Studio
89
+ session and read the results. Treat the setup line like a password. It
90
+ expires on every Studio restart.
91
+
92
+ - `connect` verifies Studio is alive over HTTPS, saves the channel id,
93
+ and prints the manual. Read both files here before running anything, or
94
+ pass `--print` to verify without saving.
95
+ - `connect` only accepts hex channel IDs, talks HTTPS to the relay only
96
+ (never follows redirects), times out stalled requests, and caps response
97
+ sizes. The only data it acts on is a small `ping` reply.
98
+ - There are no baked-in Firebase credentials or signing keys: the channel
99
+ ID itself is the capability, and transport runs over HTTPS. Public client
100
+ code cannot hold a secret, so any "signed responses" scheme here would be
101
+ theater rather than security.
102
+ - Socket.dev flags the "URL strings" in this package (the relay address).
103
+ That is informational: the relay address is the product.
104
+ - Scanners also flag the Lua execution and editing commands. That is
105
+ what Golem is: your agent driving your own Studio. The session key
106
+ (16 hex chars, rotated every start, revocable in one click) is the
107
+ whole security model.