feat: versioned WS envelope (v:1) + capabilities in hello

Every control-channel message now carries a protocol version field so
the gateway can evolve the wire format without guessing. The hello
handshake announces device capabilities (tool list with descriptions,
shell allowlist/unsafe flag, platform) so the control plane can enforce
agent_permissions without probing the device.

- control.js: #send adds v:1; hello includes capabilities
- agent.js: passes tools.list() + shell security posture
- shell.js: exports security { allowlist, unsafe, platform }
- tests: hello envelope shape + capabilities

src/agent.js

@@ -7,6 +7,7 @@ import { EventEmitter } from 'node:events';
 import { think } from './cloud.js';
 import { ControlChannel } from './control.js';
 import { tools } from './tools/index.js';
+import { security as shellSecurity } from './tools/shell.js';
 import { log } from './log.js';
 
 export class AgentDaemon extends EventEmitter {
@@ -20,7 +21,10 @@ export class AgentDaemon extends EventEmitter {
     super();
     this.#creds = creds;
 
-    this.#control = new ControlChannel(creds.apiKey, creds.agentId);
+    this.#control = new ControlChannel(creds.apiKey, creds.agentId, {
+      tools: tools.list(),
+      shell: shellSecurity,
+    });
 
     // Forward control events
     this.#control.on('connected',    ()    => this.emit('connected'));

src/control.js

@@ -20,6 +20,7 @@ const TERMINAL_CLOSE_CODES = new Set([4001, 4003]);
 export class ControlChannel extends EventEmitter {
   #apiKey;
   #agentId;
+  #capabilities;
   #ws = null;
   #queue = [];
   #metricsTimer = null;
@@ -28,10 +29,11 @@ export class ControlChannel extends EventEmitter {
   #closing = false;
   #stopped = false;
 
-  constructor(apiKey, agentId) {
+  constructor(apiKey, agentId, capabilities = null) {
     super();
     this.#apiKey = apiKey;
     this.#agentId = agentId;
+    this.#capabilities = capabilities;
   }
 
   /** Connect (or reconnect) to the cloud. Returns this for chaining. */
@@ -61,6 +63,7 @@ export class ControlChannel extends EventEmitter {
         cpus:     os.cpus().length,
         mem:      os.totalmem(),
         version:  DEFAULTS.version,
+        capabilities: this.#capabilities,
       });
       this.#flush();
       this.#startMetrics();
@@ -109,9 +112,10 @@ export class ControlChannel extends EventEmitter {
     return this;
   }
 
-  /** Send a typed message upstream. */
+  /** Send a typed message upstream. Every envelope carries a protocol version. */
   #send(type, data) {
     const msg = JSON.stringify({
+      v: 1,
       type,
       ts: Date.now(),
       agentId: this.#agentId,

src/tools/shell.js

@@ -42,6 +42,14 @@ const ALLOW = new Set(
 );
 const UNSAFE = process.env.MONA_SHELL_UNSAFE === '1';
 
+/** Shell security posture — advertised to the cloud in `hello` so the
+ *  control plane can enforce agent_permissions without probing. */
+export const security = {
+  allowlist: [...ALLOW].sort(),
+  unsafe: UNSAFE,
+  platform: PLATFORM,
+};
+
 // ── Per-OS command mapping (translate common unix → windows) ──────
 const CMD_MAP_WIN32 = {
   ls: 'dir',

test/control.test.mjs

@@ -15,11 +15,15 @@ const { ControlChannel } = await import('../src/control.js');
 
 let connections = 0;
 let closeCode = null;
+let lastHello = null;
 server.on('connection', (ws) => {
   connections++;
   ws.on('message', (raw) => {
     const msg = JSON.parse(raw.toString());
-    if (msg.type === 'hello') ws.send(JSON.stringify({ type: 'pong', data: {} }));
+    if (msg.type === 'hello') {
+      lastHello = msg;
+      ws.send(JSON.stringify({ type: 'pong', data: {} }));
+    }
   });
   if (closeCode !== null) {
     // 1006 is reserved and can never be sent as a close frame — terminate()
@@ -29,7 +33,7 @@ server.on('connection', (ws) => {
   }
 });
 
-const reset = () => { connections = 0; };
+const reset = () => { connections = 0; lastHello = null; };
 
 // terminate() produces an ECONNRESET on the client — expected in the 1006 test.
 const quiet = (ch) => ch.on('error', () => {});
@@ -120,4 +124,31 @@ describe('control channel', () => {
     assert.equal(flushed, true);
     ch.close();
   });
+
+  it('sends v:1 envelope and announces capabilities in hello', async () => {
+    reset();
+    closeCode = null;
+    const caps = {
+      tools: [{ name: 'sysinfo', description: 'System information' }],
+      shell: { allowlist: ['df', 'uptime'], unsafe: false, platform: 'darwin' },
+    };
+    const ch = new ControlChannel('test-key', 'agent-1', caps);
+    quiet(ch);
+    ch.connect();
+
+    await new Promise((resolve) => {
+      const timer = setInterval(() => {
+        if (lastHello) { clearInterval(timer); resolve(); }
+      }, 25);
+    });
+
+    assert.equal(lastHello.v, 1);
+    assert.equal(lastHello.agentId, 'agent-1');
+    assert.ok(Array.isArray(lastHello.data.capabilities.tools));
+    assert.equal(lastHello.data.capabilities.tools[0].name, 'sysinfo');
+    assert.deepEqual(lastHello.data.capabilities.shell.allowlist, ['df', 'uptime']);
+    assert.ok(lastHello.data.host);
+    assert.ok(lastHello.data.version);
+    ch.close();
+  });
 });