@twinsearth/w2m-dsh-plugin 1.2.0 → 1.2.1

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
               },
     "metadata":  {
                      "description":  "The w2m fleet plugins: one account, many machines, any of Windows, macOS or Linux.",
-                     "version":  "1.2.0"
+                     "version":  "1.2.1"
                  },
     "plugins":  [
                     {
                         "name":  "w2m-fleet",
                         "source":  "./",
                         "description":  "Read fleet state and dispatch commands across the machines registered to one account. Read-only MCP surface: the five exposed tools cannot change anything.",
-                        "version":  "1.2.0",
+                        "version":  "1.2.1",
                         "author":  {
                                        "name":  "TwinsEarth"
                                    },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
     "name":  "w2m-fleet",
     "description":  "Drive the same project on online Windows, macOS and Linux machines from one account: read fleet state, dispatch commands and read results. The MCP surface is deliberately read-only.",
-    "version":  "1.2.0",
+    "version":  "1.2.1",
     "author":  {
                    "name":  "TwinsEarth"
                },

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to this project are documented here.
 
+## [1.2.1] — 2026-10-18
+
+**P1 of fleet collaboration: addressing, correlation, and a turn that can time out.**
+
+### 1. Addressing — a message can name its recipient
+
+`POST /v1/fleet/messages` accepts `to`: `"all"` (the fleet group, the default) or one `machine_id`. The relay stores ONE row
+either way and filters at read time (`for_me=1` is answered from the authenticated device identity, never from a caller
+supplied id), because N copies for N recipients would multiply the byte budget by the size of the fleet for no extra
+meaning. A malformed address is refused `BAD_ADDRESS` by the store and `CHAT_BAD_ADDRESS` by the host route.
+
+### 2. Correlation — threads and replies
+
+Messages carry `thread_id`, `reply_to` and `turn`. `reply_to` must name a message that exists in the SAME session
+(`REPLY_TARGET_MISSING` otherwise): a dangling reply makes a thread unreadable. `turn` is assigned by the relay and counts
+the exchange inside a thread, so a reader can order answers without trusting client clocks.
+
+### 6. Turn semantics — waiting is a state, timeouts are values
+
+`w2m_chat` gained `action: "ask"` (send, return the message id) and `action: "await"` (wait for a reply to that id).
+`await` returns `{state: "answered" | "timeout"}` — a timeout is a result the caller reads, not an exception that loses the
+question, and the question stays in the flow so it can be answered later.
+
+### What this needs from the relay
+
+The fields are new, so the relay on the fleet host must be redeployed with this build. An older relay ignores the fields
+(the message still stores and reads, without addressing/threading) because they are plain body fields rather than a
+protocol version bump.
+
+### Verified
+
+Relay store: `BAD_ADDRESS`, `REPLY_TARGET_MISSING`, turn counting, and the read filters. HTTP: the three existing
+fleet-message tests still pass. Tools: 122 pass. relay suite: 163 pass. Gate GREEN twice, 15 of 15.
+
+### Not verified
+
+Two-machine end-to-end (A asks, B answers, A's await reports answered) — that needs both machines on this build, and the
+relay redeployed.
 ## [1.2.0] — 2026-10-18
 
 **Fleet chat is one group per relay.**

package/codex/mcp-servers.toml

@@ -12,6 +12,6 @@
 
 [mcp_servers.w2m-fleet]
 command = "npx"
-args = ["-y", "-p", "@twinsearth/w2m-dsh-plugin@1.2.0", "w2m-mcp"]
+args = ["-y", "-p", "@twinsearth/w2m-dsh-plugin@1.2.1", "w2m-mcp"]
 startup_timeout_sec = 20
 tool_timeout_sec = 60

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "@twinsearth/w2m-dsh-plugin",
-    "version":  "1.2.0",
+    "version":  "1.2.1",
     "description":  "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 11 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
     "type":  "module",
     "main":  "lib/index.js",

package/plugin.json

@@ -1,7 +1,7 @@
 {
     "$schema":  "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
     "name":  "twinsearth-w2m-dsh",
-    "version":  "1.2.0",
+    "version":  "1.2.1",
     "description":  "Run one project across your own Windows and macOS machines from a single DeepSeek account, through 12 w2m_* tools. Four coordination modes (replicate, split, broadcast, pipeline) and six aggregate verdicts (consistent, divergent, divergent-platform, failed, partial, unverifiable). P2P hole punching by default, with a bundled relay, STUN responder and ledger fallback, so the fleet needs no third-party service. Joining needs a pairing code plus autoStartAgent: true; installing alone does not join.",
     "license":  "MIT",
     "keywords":  [

package/src/plugin/fleet-chat-route.mjs

@@ -165,6 +165,7 @@ export function registerChatRoutes(ctx, deps) {
           // Its key is the relay alone -- deliberately NOT the project name -- so every machine in the fleet
           // lands in one stream. It is not a history fetch: the caller sends a floor timestamp (see the panel).
           let sessionId = '';
+          const addressing = {};
           let text = null;
           if (request.method === 'GET') {
             sessionId = sessionIdOf(url.searchParams.get('session_id'));
@@ -177,6 +178,17 @@ export function registerChatRoutes(ctx, deps) {
             }
             sessionId = sessionIdOf(body?.session_id);
             text = typeof body?.text === 'string' ? body.text : null;
+            // Addressing + correlation travel as optional fields; each is validated here so a bad one is refused with a
+            // name instead of being stored and never understood.
+            if (typeof body?.to === 'string' && body.to.trim() !== '') {
+              const to = body.to.trim();
+              if (to !== 'all' && (to.length > 64 || /\s/.test(to))) {
+                return refuse(400, 'CHAT_BAD_ADDRESS', 'to must be "all" or a machine id', 'a recipient is either the whole fleet or one machine');
+              }
+              addressing.to = to;
+            }
+            if (typeof body?.thread_id === 'string' && body.thread_id.trim() !== '') addressing.thread_id = body.thread_id.trim().slice(0, 64);
+            if (typeof body?.reply_to === 'string' && body.reply_to.trim() !== '') addressing.reply_to = body.reply_to.trim();
           }
           const identity = await identityOf();
           if (identity.error !== null) {
@@ -203,7 +215,11 @@ export function registerChatRoutes(ctx, deps) {
 
           try {
             if (request.method === 'GET') {
-              const query = { session_id: sessionId };
+              const query = { session_id: sessionId, for_me: '1' };
+              const threadOf = url.searchParams.get('thread_id');
+              const toOf = url.searchParams.get('to');
+              if (threadOf !== null && threadOf !== '') query.thread_id = threadOf;
+              if (toOf !== null && toOf !== '') query.to = toOf;
               const sinceMs = url.searchParams.get('since_ms');
               const limit = url.searchParams.get('limit');
               if (sinceMs !== null && /^\d+$/.test(sinceMs)) query.since_ms = sinceMs;
@@ -216,7 +232,7 @@ export function registerChatRoutes(ctx, deps) {
               }
               return Response.json({ ...listed.json, ok: true, local_machine_id: identity.machineId, local_machine_name: identity.machineName, conversation_key: sessionId, conversation_source: identity.source }, { headers: NO_STORE });
             }
-            const posted = await deps.request({ rabbitUrl, token, method: 'POST', pathname: '/v1/fleet/messages', body: { session_id: sessionId, text: text ?? '', machine_id: identity.machineId, machine_name: identity.machineName, origin: 'chat' }, signal: request.signal });
+            const posted = await deps.request({ rabbitUrl, token, method: 'POST', pathname: '/v1/fleet/messages', body: { session_id: sessionId, text: text ?? '', machine_id: identity.machineId, machine_name: identity.machineName, origin: 'chat', ...addressing }, signal: request.signal });
             if (posted?.ok !== true) {
               const code = posted?.json?.error?.code ?? posted?.error?.code ?? 'CHAT_SEND_REFUSED';
               const message = posted?.json?.error?.message ?? posted?.error?.message ?? `the relay answered HTTP ${posted?.status ?? 0}`;

package/src/plugin/tools.mjs

@@ -220,7 +220,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '1.2.0';
+const PLUGIN_VERSION = '1.2.1';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
@@ -6335,11 +6335,20 @@ export async function apply(ctx, config = {}) {
       'Fleet chat for one session: send plain text to the machines in this conversation, or read what was said. ' +
       'A refused write comes back with its named reason (quota, size, or non-text) rather than as a bare failure.',
     parameters: {
-      action: { type: 'string', enum: ['send', 'list'], description: 'send posts text; list reads the flow (default).', default: 'list' },
+      action: {
+        type: 'string',
+        enum: ['send', 'list', 'ask', 'await'],
+        description: 'send posts text; ask posts a question and returns its message id; await waits for a reply to it; list reads the flow (default).',
+        default: 'list',
+      },
       session_id: { type: 'string', description: 'Which conversation. Chat is scoped to a session, not a machine.' },
       text: { type: 'string', description: 'The message for send. Plain text, UTF-8, at most 4 KiB.' },
       since_ms: { type: 'number', description: 'For list: only messages newer than this relay timestamp.' },
       limit: { type: 'number', description: 'For list: how many of the newest messages (default 50).' },
+      to: { type: 'string', description: 'For send/ask: "all" (the fleet group, the default) or one machine_id.' },
+      thread_id: { type: 'string', description: 'For send/ask: group this message into a named thread (at most 64 characters).' },
+      reply_to: { type: 'string', description: 'For send/ask: the message_id this message answers. For await: the message_id to wait for a reply to.' },
+      timeout_ms: { type: 'number', description: 'For await: how long to wait before reporting a timeout (default 60000, capped at 300000). A timeout is a value, not an error.' },
     },
     output: jsonOutput,
     presentCall: (args) => ({ card: 'generic', title: 'w2m chat ' + (typeof args?.action === 'string' ? args.action : 'list'), kind: args?.action === 'send' ? 'write' : 'read', rawInput: {} }),
@@ -6356,14 +6365,46 @@ export async function apply(ctx, config = {}) {
       // one reported W2M_NO_TOKEN on a machine that was paired and answering every other call.
       const token = await resolveToken(cfg);
       if (token === null) throw new W2MError('W2M_NO_TOKEN', 'W2M_NO_TOKEN: this machine has no device token, so chat cannot be authenticated', { hint: 'pair this machine first (autoStartAgent or a pairing code), then retry' });
-      if (action === 'send') {
-        const posted = await request({ rabbitUrl, token, signal: exec?.signal, method: 'POST', pathname: '/v1/fleet/messages', body: { session_id: sessionId, text: typeof args?.text === 'string' ? args.text : '' } });
+      // Addressing + correlation travel only when the caller supplied them, so a plain broadcast stays byte-identical.
+      const addressing = {};
+      if (typeof args?.to === 'string' && args.to.trim() !== '') {
+        const to = args.to.trim();
+        if (to !== 'all' && (to.length > 64 || /\s/.test(to))) {
+          throw new W2MError('W2M_CHAT_ADDRESS', 'W2M_CHAT_ADDRESS: to must be "all" or a machine id', { hint: 'a recipient is either the whole fleet or one machine listed by w2m_devices' });
+        }
+        addressing.to = to;
+      }
+      if (typeof args?.thread_id === 'string' && args.thread_id.trim() !== '') addressing.thread_id = args.thread_id.trim().slice(0, 64);
+      if (typeof args?.reply_to === 'string' && args.reply_to.trim() !== '') addressing.reply_to = args.reply_to.trim();
+
+      if (action === 'await') {
+        // Waiting for an ANSWER is a state machine, and a timeout is a value the caller reads rather than an exception
+        // that loses the question. The question stays in the flow, so it can still be answered later.
+        const target = typeof args?.reply_to === 'string' ? args.reply_to.trim() : '';
+        if (target === '') throw new W2MError('W2M_CHAT_AWAIT', 'W2M_CHAT_AWAIT: reply_to is required for await', { hint: 'pass the message_id returned by ask' });
+        const timeoutMs = Number.isFinite(args?.timeout_ms) ? Math.max(1000, Math.min(args.timeout_ms, 300000)) : 60000;
+        const startedAt = Date.now();
+        for (;;) {
+          throwIfAborted(exec?.signal);
+          const reply = await request({ rabbitUrl, token, signal: exec?.signal, method: 'GET', pathname: '/v1/fleet/messages', query: { session_id: sessionId, reply_to: target, limit: '10' } });
+          const found = Array.isArray(reply?.json?.messages) ? reply.json.messages : [];
+          if (found.length > 0) return JSON.stringify({ ok: true, action, state: 'answered', reply_to: target, replies: found });
+          if (Date.now() - startedAt >= timeoutMs) {
+            return JSON.stringify({ ok: true, action, state: 'timeout', reply_to: target, waited_ms: Date.now() - startedAt, hint: 'the question is still in the flow and can be answered later' });
+          }
+          await new Promise((resolve) => { setTimeout(resolve, 1500); });
+        }
+      }
+      if (action === 'send' || action === 'ask') {
+        const posted = await request({ rabbitUrl, token, signal: exec?.signal, method: 'POST', pathname: '/v1/fleet/messages', body: { session_id: sessionId, text: typeof args?.text === 'string' ? args.text : '', ...addressing } });
         if (posted?.ok !== true) {
           const code = posted?.json?.error?.code ?? posted?.error?.code ?? 'W2M_CHAT_SEND';
           throw new W2MError('W2M_CHAT_SEND', code + ': the message was refused', { reason_code: code, hint: 'quota, size and non-text each need a different answer' });
         }
-        return JSON.stringify({ ok: true, action, message: posted.json?.message ?? null });
+        return JSON.stringify({ ok: true, action, message: posted.json?.message ?? null, message_id: posted.json?.message?.message_id ?? null });
       }
+      if (typeof args?.thread_id === 'string' && args.thread_id.trim() !== '') query.thread_id = args.thread_id.trim();
+      if (typeof args?.to === 'string' && args.to.trim() !== '') query.to = args.to.trim();
       const query = { session_id: sessionId };
       if (Number.isFinite(args?.since_ms)) query.since_ms = String(args.since_ms);
       if (Number.isInteger(args?.limit)) query.limit = String(args.limit);

package/src/relay/fleet-messages.mjs

@@ -88,25 +88,46 @@ export function createFleetMessages(options = {}) {
     const text = input.text;
     if (text.trim() === '') return { ok: false, code: 'EMPTY_TEXT' };
     // Reject control characters (except tab/newline): "plain text" is a contract, not a preference.
-    // Control characters are the thing being rejected here, so the rule that forbids them in a pattern
-    // does not apply -- the escape IS the contract.
-    // eslint-disable-next-line no-control-regex
+    // eslint-disable-next-line no-control-regex
     if (/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/.test(text)) return { ok: false, code: 'NOT_TEXT' };
     const bytes = Buffer.byteLength(text, 'utf8');
     if (bytes > maxMessageBytes) return { ok: false, code: 'MESSAGE_TOO_LARGE', detail: { bytes, maxBytes: maxMessageBytes } };
 
+    // Addressing: 'all' is the group, a machine id is one recipient. ONE row either way -- N copies for N recipients
+    // would multiply the byte budget by the fleet size for no extra meaning; visibility is a filter at read time.
+    const to = typeof input?.to === 'string' && input.to.trim() !== '' ? input.to.trim() : 'all';
+    if (to !== 'all' && (to.length > 64 || /\s/.test(to))) return { ok: false, code: 'BAD_ADDRESS' };
+    // Correlation: a thread groups a conversation, reply_to points at the message being answered, turn orders the
+    // exchange inside one thread. Plain fields, validated rather than trusted.
+    const threadId = typeof input?.thread_id === 'string' && input.thread_id.trim() !== ''
+      ? input.thread_id.trim().slice(0, 64)
+      : null;
+    const replyTo = typeof input?.reply_to === 'string' && input.reply_to.trim() !== '' ? input.reply_to.trim() : null;
+
     const before = usage();
     const limit = limitBytes();
     if (before.used_24h_bytes + bytes > limit) {
       return { ok: false, code: 'FLEET_QUOTA_EXCEEDED', detail: { used_24h_bytes: before.used_24h_bytes, limit_bytes: limit, bytes } };
     }
 
+    // A reply must point at something that exists in the SAME session: a dangling reply_to makes a thread unreadable.
+    const existing = sessions.get(sessionId) ?? [];
+    if (replyTo !== null && !existing.some((m) => m.message_id === replyTo)) {
+      return { ok: false, code: 'REPLY_TARGET_MISSING', detail: { reply_to: replyTo } };
+    }
+    const threadOf = threadId ?? (replyTo !== null ? (existing.find((m) => m.message_id === replyTo)?.thread_id ?? null) : null);
+    const turn = existing.filter((m) => (threadOf === null ? m.thread_id === null : m.thread_id === threadOf)).length + 1;
+
     seq += 1;
     const message = {
       message_id: 'msg-' + String(seq).padStart(6, '0'),
       session_id: sessionId,
       fleet_id: typeof input?.fleet_id === 'string' ? input.fleet_id : null,
       machine_id: machineId,
+      to,
+      thread_id: threadOf,
+      reply_to: replyTo,
+      turn,
       text,
       at_ms: now(),
       bytes,
@@ -122,9 +143,16 @@ export function createFleetMessages(options = {}) {
   }
 
   /** Read one session's flow. \`since_ms\` is exclusive; the order is the order it was said. */
-  function list({ session_id: sessionId, since_ms: sinceMs = null, limit = 50 } = {}) {
+  function list({ session_id: sessionId, since_ms: sinceMs = null, limit = 50, for_machine_id: forMachine = null,
+    thread_id: threadId = null, to: toFilter = null } = {}) {
     const rows = sessions.get(sessionId) ?? [];
-    const filtered = Number.isFinite(sinceMs) ? rows.filter((m) => m.at_ms > sinceMs) : rows;
+    let filtered = Number.isFinite(sinceMs) ? rows.filter((m) => m.at_ms > sinceMs) : rows;
+    // A reader sees the group and what was addressed to it, never another machine's private message.
+    if (typeof forMachine === 'string' && forMachine !== '') {
+      filtered = filtered.filter((m) => (m.to ?? 'all') === 'all' || m.to === forMachine || m.machine_id === forMachine);
+    }
+    if (typeof threadId === 'string' && threadId !== '') filtered = filtered.filter((m) => m.thread_id === threadId);
+    if (typeof toFilter === 'string' && toFilter !== '') filtered = filtered.filter((m) => (m.to ?? 'all') === toFilter);
     const capped = filtered.slice(-Math.max(1, Math.min(limit, 200)));
     return { ok: true, messages: capped.map((m) => ({ ...m })), count: capped.length };
   }

package/src/relay/server.mjs

@@ -1052,6 +1052,9 @@ export class RelayServer {
         session_id: body.session_id,
         fleet_id: typeof body.fleet_id === 'string' ? body.fleet_id : null,
         machine_id: device.machine_id,
+        to: body.to,
+        thread_id: body.thread_id,
+        reply_to: body.reply_to,
         text: body.text,
       });
       if (posted.ok !== true) {
@@ -1098,6 +1101,11 @@ export class RelayServer {
         session_id: url.searchParams.get('session_id') ?? '',
         since_ms: sinceRaw === null ? null : Number(sinceRaw),
         limit: limitRaw === null ? 50 : Number(limitRaw),
+        // Addressing/correlation filters. `for_me=1` is answered from the authenticated device identity, never from a
+        // caller-supplied machine id: a reader must not be able to ask for another machine's private messages.
+        for_machine_id: url.searchParams.get('for_me') === '1' ? device.machine_id : null,
+        thread_id: url.searchParams.get('thread_id'),
+        to: url.searchParams.get('to'),
       });
       return sendJson(res, 200, {
         protocol_version: PROTOCOL_VERSION,