@hncode/hncode 0.5.2 → 0.5.4

package/src/swarm-progress.js

@@ -3,7 +3,7 @@
 // kimi does NOT render a swarm as a tool line plus a text dump. It renders a live
 // BLOCK in the transcript:
 //
-//   ─ Agent Swarm ─ 两个子代理各回你好 ─ coder
+//   ─ Agent Swarm ─ two subagents each replied hi ─ coder
 //
 //     001 [#---------------] Working…   Inspecting src/tui.js
 //     002 [###-------------] Queued…

package/src/team/mailbox.js

@@ -1,139 +1,216 @@
-// The mailbox: one inbox file per member, addressed by name.
-//
-//   ~/.hncode/teams/<team>/inboxes/<name>.json   ->  TeammateMessage[]
-//
-// WHY A FILE PER RECIPIENT
-// ------------------------
-// A single shared log would need every reader to track its own watermark, and a member that
-// restarts would re-read everything it had already seen. Per-recipient files make "what is
-// waiting for me" a plain read, and marking read is a write to your own file only — no member
-// contends with another over the same one.
-//
-// WRITES ARE ATOMIC
-// -----------------
-// Write to a temp file, then rename. `rename` is atomic on every platform we run on, so a
-// reader either sees the whole previous inbox or the whole new one — never a half-written JSON
-// that parses as nothing and silently drops the mail. This also covers the cross-process case
-// (two hncode sessions in the same team), where an in-process mutex would not.
-import fs from 'node:fs';
-import path from 'node:path';
-import { inboxDir, inboxPath } from './store.js';
-
-/**
- * A message as it sits in an inbox.
- *
- * `read` lives on the message rather than in a separate watermark file: it travels with the
- * message when the inbox is rewritten, and a member reading its own inbox is the only writer.
- */
-export const MAX_INBOX = 500;
-
-function writeAtomic(file, text) {
-  const dir = path.dirname(file);
-  fs.mkdirSync(dir, { recursive: true });
-  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
-  fs.writeFileSync(tmp, text, 'utf8');
-  try {
-    fs.renameSync(tmp, file);
-  } catch (e) {
-    try { fs.unlinkSync(tmp); } catch { /* the tmp is worthless now */ }
-    throw e;
-  }
-}
-
-/** Every message in a member's inbox, oldest first. Never throws. */
-export function readMailbox(teamName, agentName) {
-  try {
-    const parsed = JSON.parse(fs.readFileSync(inboxPath(teamName, agentName), 'utf8'));
-    return Array.isArray(parsed) ? parsed : [];
-  } catch {
-    return [];
-  }
-}
-
-/** Only what the recipient has not seen. */
-export function readUnread(teamName, agentName) {
-  return readMailbox(teamName, agentName).filter((m) => !m.read);
-}
-
-/**
- * Deliver a message.
- *
- * The sender's name and colour are stamped here rather than passed by the call site, so every
- * message carries them whether it came from the lead, a teammate, or a future caller.
- */
-export function writeToMailbox(teamName, recipientName, { from, text, summary, color }) {
-  const file = inboxPath(teamName, recipientName);
-  const box = readMailbox(teamName, recipientName);
-  const msg = {
-    from: String(from || 'unknown'),
-    text: String(text == null ? '' : text),
-    timestamp: new Date().toISOString(),
-    read: false,
-  };
-  if (summary) msg.summary = String(summary);
-  if (color) msg.color = String(color);
-  box.push(msg);
-  // Bounded: an inbox nobody drains must not grow without limit and turn every read into a
-  // parse of the whole session's chatter.
-  const kept = box.length > MAX_INBOX ? box.slice(box.length - MAX_INBOX) : box;
-  writeAtomic(file, JSON.stringify(kept, null, 2));
-  return msg;
-}
-
-/**
- * Mark the given messages read. Returns how many changed.
- *
- * `ids` are timestamps, not array positions: the box is re-read here, and a message
- * delivered in between would shift every later index — marking by position would then
- * silence the wrong message, or one that was never delivered at all.
- *
- * When called with no `ids` every message is marked, which is what a caller that
- * genuinely drained the whole box wants. A caller that PROCESSED a specific batch must
- * pass it: blanket-marking re-reads the box and marks whatever arrived since the
- * batch was taken, and those messages are then never delivered.
- */
-export function markAllRead(teamName, agentName, ids = null) {
-  const box = readMailbox(teamName, agentName);
-  const want = Array.isArray(ids) ? new Set(ids.map((m) => (m && m.timestamp) || m)) : null;
-  let n = 0;
-  for (const m of box) {
-    if (m.read) continue;
-    if (want && !want.has(m.timestamp)) continue;
-    m.read = true;
-    n++;
-  }
-  if (n) writeAtomic(inboxPath(teamName, agentName), JSON.stringify(box, null, 2));
-  return n;
-}
-
-/** Empty a member's inbox. Used when a teammate is removed from the team. */
-export function clearMailbox(teamName, agentName) {
-  try { fs.unlinkSync(inboxPath(teamName, agentName)); return true; } catch { return false; }
-}
-
-/**
- * Render unread mail the way a member should see it: as an addressable block, not as prose.
- *
- * The `from` line matters — a teammate's next action is often "reply to whoever asked", and a
- * block of text with no name attached leaves it guessing.
- */
-export function formatInbox(messages) {
-  if (!messages.length) return '';
-  const out = [];
-  for (const m of messages) {
-    out.push(`[message from ${m.from}]`);
-    if (m.summary) out.push(`(${m.summary})`);
-    out.push(m.text);
-    out.push('');
-  }
-  return out.join('\n').trimEnd();
-}
-
-/** Every inbox file for a team, so the rota can be cleaned with the team. */
-export function listInboxes(teamName) {
-  try {
-    return fs.readdirSync(inboxDir(teamName)).filter((f) => f.endsWith('.json'));
-  } catch {
-    return [];
-  }
-}
+// The mailbox: one inbox file per member, addressed by name.
+//
+//   ~/.hncode/teams/<team>/inboxes/<name>.json   ->  TeammateMessage[]
+//
+// WHY A FILE PER RECIPIENT
+// ------------------------
+// A single shared log would need every reader to track its own watermark, and a member that
+// restarts would re-read everything it had already seen. Per-recipient files make "what is
+// waiting for me" a plain read, and marking read is a write to your own file only — no member
+// contends with another over the same one.
+//
+// WRITES ARE ATOMIC
+// -----------------
+// Write to a temp file, then rename. `rename` is atomic on every platform we run on, so a
+// reader either sees the whole previous inbox or the whole new one — never a half-written JSON
+// that parses as nothing and silently drops the mail. This also covers the cross-process case
+// (two hncode sessions in the same team), where an in-process mutex would not.
+import fs from 'node:fs';
+import path from 'node:path';
+import { inboxDir, inboxPath } from './store.js';
+
+/**
+ * A message as it sits in an inbox.
+ *
+ * `read` lives on the message rather than in a separate watermark file: it travels with the
+ * message when the inbox is rewritten, and a member reading its own inbox is the only writer.
+ */
+export const MAX_INBOX = 500;
+
+function writeAtomic(file, text) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, text, 'utf8');
+  try {
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch { /* the tmp is worthless now */ }
+    throw e;
+  }
+}
+
+/** Every message in a member's inbox, oldest first. Never throws.
+ *
+ *  Cached by (mtimeMs, size): the panel renders rosters and traffic per frame,
+ *  and waitForMail polls 4x/second — a stat per read replaces the full
+ *  readFileSync + JSON.parse. Writes go through writeAtomic (rename), which
+ *  always changes the mtime, so nothing stale survives. The cached array is
+ *  copied on the way out: a caller that mutates the result without writing
+  *  back must not corrupt the cache. */
+const _mbCache = new Map();   // inbox file -> { key, box }
+export function readMailbox(teamName, agentName) {
+  const file = inboxPath(teamName, agentName);
+  let st = null;
+  try { st = fs.statSync(file); } catch { /* absent */ }
+  if (!st) return [];
+  const key = `${st.mtimeMs}:${st.size}`;
+  const hit = _mbCache.get(file);
+  if (hit && hit.key === key) return hit.box.slice();
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const box = Array.isArray(parsed) ? parsed : [];
+    _mbCache.set(file, { key, box });
+    if (_mbCache.size > 64) { // bounded: one entry per inbox ever read
+      const first = _mbCache.keys().next().value;
+      _mbCache.delete(first);
+    }
+    return box.slice();
+  } catch {
+    _mbCache.delete(file);
+    return [];
+  }
+}
+
+/** Only what the recipient has not seen. */
+export function readUnread(teamName, agentName) {
+  return readMailbox(teamName, agentName).filter((m) => !m.read);
+}
+
+/**
+ * A monotonic counter for ordering messages ACROSS mailboxes.
+ *
+ * `timestamp` cannot do it: it has millisecond resolution, and two messages written in the same
+ * millisecond in two different inbox files compare equal — the sort then falls back to file position,
+ * which is only meaningful WITHIN one file. That is how a user's two messages appeared above the reply
+ * that answered the first of them.
+ *
+ * Process-local is enough: every inbox write in a team goes through this module in one process.
+ */
+let seqCounter = 0;
+
+
+/**
+ * Deliver a message.
+ *
+ * The sender's name and colour are stamped here rather than passed by the call site, so every
+ * message carries them whether it came from the lead, a teammate, or a future caller.
+ */
+export function writeToMailbox(teamName, recipientName, { from, text, summary, color }) {
+  const file = inboxPath(teamName, recipientName);
+  const box = readMailbox(teamName, recipientName);
+  seqCounter += 1;
+  const msg = {
+    from: String(from || 'unknown'),
+    text: String(text == null ? '' : text),
+    timestamp: new Date().toISOString(),
+    // Ordering key. Milliseconds alone leave two boxes' messages tied, and the panel then interleaves
+    // them wrongly.
+    seq: seqCounter,
+    read: false,
+  };
+  if (summary) msg.summary = String(summary);
+  if (color) msg.color = String(color);
+  box.push(msg);
+  // Bounded: an inbox nobody drains must not grow without limit and turn every read into a
+  // parse of the whole session's chatter.
+  const kept = box.length > MAX_INBOX ? box.slice(box.length - MAX_INBOX) : box;
+  writeAtomic(file, JSON.stringify(kept, null, 2));
+  return msg;
+}
+
+/**
+ * Mark the given messages read. Returns how many changed.
+ *
+ * `ids` are MESSAGE IDENTITIES (seq, falling back to timestamp for pre-seq boxes), not
+ * array positions: the box is re-read here, and a message delivered in between would
+ * shift every later index — marking by position would then silence the wrong message,
+ * or one that was never delivered at all.
+ *
+ * When called with no `ids` every message is marked, which is what a caller that
+ * genuinely drained the whole box wants. A caller that PROCESSED a specific batch must
+ * pass it: blanket-marking re-reads the box and marks whatever arrived since the
+ * batch was taken, and those messages are then never delivered.
+ */
+export function markAllRead(teamName, agentName, ids = null) {
+  const box = readMailbox(teamName, agentName);
+  let n = 0;
+  // Keyed by `seq` — the same identity removeMail uses. Two messages delivered in
+  // the same millisecond share a timestamp (a broadcast and a direct mail landing
+  // together), and keying on the timestamp marked the sibling read too, so it was
+  // never delivered to the model. Timestamps remain a fallback for boxes written
+  // by an older build, whose messages carry no seq.
+  const wantSeq = new Set();
+  const wantTs = new Set();
+  if (Array.isArray(ids)) {
+    for (const id of ids) {
+      if (id && typeof id === 'object') {
+        if (id.seq != null) wantSeq.add(Number(id.seq));
+        else if (id.timestamp) wantTs.add(id.timestamp);
+      } else if (id != null) wantTs.add(id);
+    }
+  }
+  for (const m of box) {
+    if (m.read) continue;
+    if (Array.isArray(ids)) {
+      const bySeq = m.seq != null && wantSeq.has(Number(m.seq));
+      if (!bySeq && !wantTs.has(m.timestamp)) continue;
+    }
+    m.read = true;
+    n++;
+  }
+  if (n) writeAtomic(inboxPath(teamName, agentName), JSON.stringify(box, null, 2));
+  return n;
+}
+
+/** Empty a member's inbox. Used when a teammate is removed from the team. */
+export function clearMailbox(teamName, agentName) {
+  try { fs.unlinkSync(inboxPath(teamName, agentName)); return true; } catch { return false; }
+}
+
+/**
+ * Delete specific messages from a box, by `seq`. Returns how many went.
+ *
+ * A permission RESPONSE is addressed to one member and answers one request, so it must be CONSUMED: a
+ * plain read flag is not enough, because the member polls in a loop and would see the same answer again
+ * on its next request — authorising a call the person never approved.
+ *
+ * By `seq`, not by index or timestamp: the box is re-read here and a message delivered in between would
+ * shift every later index, while two messages in the same millisecond share a timestamp.
+ */
+export function removeMail(teamName, agentName, seqs) {
+  const want = new Set((seqs || []).map(Number));
+  if (!want.size) return 0;
+  const box = readMailbox(teamName, agentName);
+  const kept = box.filter((m) => !want.has(Number(m.seq)));
+  const removed = box.length - kept.length;
+  if (removed) writeAtomic(inboxPath(teamName, agentName), JSON.stringify(kept, null, 2));
+  return removed;
+}
+
+/**
+ * Render unread mail the way a member should see it: as an addressable block, not as prose.
+ *
+ * The `from` line matters — a teammate's next action is often "reply to whoever asked", and a
+ * block of text with no name attached leaves it guessing.
+ */
+export function formatInbox(messages) {
+  if (!messages.length) return '';
+  const out = [];
+  for (const m of messages) {
+    out.push(`[message from ${m.from}]`);
+    if (m.summary) out.push(`(${m.summary})`);
+    out.push(m.text);
+    out.push('');
+  }
+  return out.join('\n').trimEnd();
+}
+
+/** Every inbox file for a team, so the rota can be cleaned with the team. */
+export function listInboxes(teamName) {
+  try {
+    return fs.readdirSync(inboxDir(teamName)).filter((f) => f.endsWith('.json'));
+  } catch {
+    return [];
+  }
+}

package/src/team/permission.js

@@ -0,0 +1,121 @@
+// Permission requests, routed from a member to the person through the team mailbox.
+//
+// WHY THIS FILE EXISTS
+// --------------------
+// A teammate runs tools that can write files and execute commands. Until now it had exactly two options:
+// be allowed to do anything, or be unable to ask. There was no middle — nothing carried "may I run this?"
+// from the member to the person who could answer, and nothing carried the answer back.
+//
+// The protocol is the mailbox, because it is the only channel that already reaches both ends:
+//
+//   1. the member blocks on a tool it may not run and writes a `permission_request` to the lead's box
+//   2. the TUI shows it (the lead's inbox is already drained every turn)
+//   3. the person approves or refuses; a `permission_response` goes to the member's box
+//   4. the member's runner polls for the response, matches it by `request_id`, and continues
+//
+// `request_id` is what makes this correct rather than a race: a member may have several calls in flight,
+// and a response that arrived for an earlier one must not authorise a later one.
+import { writeToMailbox, readMailbox, removeMail } from './mailbox.js';
+import { newRequestId, parseProtocol } from './protocol.js';
+
+/** How long a member waits for an answer before giving up. Long: a person may be away. */
+export const PERMISSION_TIMEOUT_MS = 10 * 60 * 1000;
+
+/** How often the member looks for its answer. */
+const POLL_MS = 250;
+
+/**
+ * A member asks for permission and BLOCKS until the lead answers.
+ *
+ * Resolves to `{ approved: false, error }` on refusal and on timeout — never throws, because the caller is
+ * mid-turn and an exception here would end a member that merely needed a decision. A timeout is reported
+ * as a refusal WITH ITS REASON, so the model is told the difference between "no" and "nobody answered".
+ */
+export async function requestPermission({
+  teamName,
+  memberName,
+  leadName,
+  toolName,
+  toolUseId,
+  description,
+  input,
+  timeoutMs = PERMISSION_TIMEOUT_MS,
+  shouldStop = () => false,
+}) {
+  const requestId = newRequestId('perm');
+  writeToMailbox(teamName, leadName, {
+    from: memberName,
+    text: JSON.stringify({
+      type: 'permission_request',
+      request_id: requestId,
+      agent_id: memberName,
+      tool_name: toolName,
+      tool_use_id: toolUseId || '',
+      description: description || '',
+      input: input && typeof input === 'object' ? input : {},
+      permission_suggestions: [],
+    }),
+  });
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (shouldStop()) return { approved: false, error: 'cancelled' };
+    const answer = findResponse(teamName, memberName, requestId);
+    if (answer) return answer;
+    await new Promise((r) => setTimeout(r, POLL_MS));
+  }
+  return {
+    approved: false,
+    error: `no answer from ${leadName} within ${Math.round(timeoutMs / 1000)}s`,
+  };
+}
+
+/**
+ * Look for the answer to one request, consuming it.
+/**
+ * Look for the answer to one request, and CONSUME it.
+ *
+ * Deleted rather than flagged read: the member polls in a loop, so a response left in the box would
+ * authorise its NEXT request too — a decision the person never made.
+ */
+function findResponse(teamName, memberName, requestId) {
+  const box = readMailbox(teamName, memberName);
+  for (const m of box) {
+    const msg = parseProtocol(m.text);
+    if (!msg || msg.type !== 'permission_response') continue;
+    if (String(msg.request_id) !== String(requestId)) continue;
+    removeMail(teamName, memberName, [m.seq]);
+    if (msg.subtype === 'success') {
+      return { approved: true, updatedInput: msg.response && msg.response.updated_input };
+    }
+    return { approved: false, error: String(msg.error || 'Permission denied') };
+  }
+  return null;
+}
+
+/**
+ * The lead's side: does this inbox message ask for permission?
+ *
+ * Returns the request when it does, so the caller can put it in front of the person. A message that is
+ * not a permission request returns null and is handled as ordinary chat by the listener.
+ */
+export function asPermissionRequest(text) {
+  const msg = parseProtocol(text);
+  if (!msg || msg.type !== 'permission_request') return null;
+  return {
+    requestId: String(msg.request_id || ''),
+    agentId: String(msg.agent_id || ''),
+    toolName: String(msg.tool_name || ''),
+    toolUseId: String(msg.tool_use_id || ''),
+    description: String(msg.description || ''),
+    input: msg.input && typeof msg.input === 'object' ? msg.input : {},
+  };
+}
+
+/** The lead answers a request. */
+export function answerPermission({ teamName, memberName, requestId, approved, error, updatedInput }) {
+  const msg = approved
+    ? { type: 'permission_response', request_id: requestId, subtype: 'success', response: updatedInput ? { updated_input: updatedInput } : {} }
+    : { type: 'permission_response', request_id: requestId, subtype: 'error', error: String(error || 'Permission denied') };
+  writeToMailbox(teamName, memberName, { from: 'team-lead', text: JSON.stringify(msg) });
+}

package/src/team/protocol.js

@@ -0,0 +1,167 @@
+// Structured messages between team members.
+//
+// WHY THIS FILE EXISTS
+// --------------------
+// Everything a team does between its members travels through the mailbox, and almost all of it needs to
+// be more than prose: a task assignment names a task ID, a shutdown request carries a correlation ID the
+// reply must echo, and a permission request has to BLOCK the sender until a matching response comes back.
+// Free text cannot carry any of that, so every consumer was reduced to matching substrings — "does this
+// message look like a shutdown?" — which works until someone writes the word in a sentence.
+//
+// The wire format is a JSON object in the message body, discriminated by `type`. A human sentence has no
+// `type` field, so plain chat and protocol traffic share one mailbox without ambiguity: parsing either
+// succeeds and says what it is, or the message is chat.
+//
+// SHAPES follow Claude Code's (`src/utils/teammateMailbox.ts`) field for field. That matters more than it
+// looks: `request_id` correlation, `task_assignment{taskId, subject, description, assignedBy}` and the
+// `permission_request{tool_name, tool_use_id, input}` triple are what let a leader's UI approve the exact
+// call a worker is blocked on. Inventing our own names here would make every one of those unanswerable.
+
+/** How a message body is recognised as protocol traffic rather than chat. */
+export const PROTOCOL_TYPES = Object.freeze([
+  'task_assignment',
+  'shutdown_request',
+  'shutdown_approved',
+  'shutdown_rejected',
+  'permission_request',
+  'permission_response',
+  'plan_approval_request',
+  'plan_approval_response',
+  'mode_set_request',
+]);
+
+/**
+ * Parse a message body as a structured message.
+ *
+ * Returns `null` for plain chat — which is the common case, so this must be cheap and must never throw.
+ * A body that happens to be JSON but carries no known `type` is also chat: the mailbox is shared, and a
+ * member discussing a JSON payload should not have its words reclassified.
+ */
+export function parseProtocol(text) {
+  const raw = String(text == null ? '' : text).trim();
+  if (!raw || raw[0] !== '{') return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  if (!PROTOCOL_TYPES.includes(parsed.type)) return null;
+  return parsed;
+}
+
+/** Is this body protocol traffic at all? */
+export function isProtocol(text) {
+  return parseProtocol(text) !== null;
+}
+
+/** A task was handed to a member. */
+export function taskAssignment({ taskId, subject, description, assignedBy }) {
+  return {
+    type: 'task_assignment',
+    taskId: String(taskId || ''),
+    subject: String(subject || ''),
+    description: String(description || ''),
+    assignedBy: String(assignedBy || ''),
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/** A leader asks a member to stop. The member answers with `shutdown_approved` or `_rejected`. */
+export function shutdownRequest({ requestId, from, reason }) {
+  return {
+    type: 'shutdown_request',
+    requestId: String(requestId || ''),
+    from: String(from || ''),
+    reason: reason ? String(reason) : undefined,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+export function shutdownApproved({ requestId, from }) {
+  return {
+    type: 'shutdown_approved',
+    requestId: String(requestId || ''),
+    from: String(from || ''),
+    timestamp: new Date().toISOString(),
+  };
+}
+
+export function shutdownRejected({ requestId, from, reason }) {
+  return {
+    type: 'shutdown_rejected',
+    requestId: String(requestId || ''),
+    from: String(from || ''),
+    reason: String(reason || ''),
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/** A member wants permission for a tool call and cannot proceed without an answer. */
+export function permissionRequest({ requestId, agentId, toolName, toolUseId, description, input }) {
+  return {
+    type: 'permission_request',
+    request_id: String(requestId || ''),
+    agent_id: String(agentId || ''),
+    tool_name: String(toolName || ''),
+    tool_use_id: String(toolUseId || ''),
+    description: String(description || ''),
+    input: input && typeof input === 'object' ? input : {},
+    permission_suggestions: [],
+  };
+}
+
+/**
+ * The leader's answer.
+ *
+ * Two shapes, discriminated by `subtype` rather than a nullable `approved`: a refusal carries a REASON,
+ * and the member shows it to the model so the next attempt can differ. A bare boolean loses that.
+ */
+export function permissionResponse({ requestId, approved, error, updatedInput }) {
+  if (!approved) {
+    return {
+      type: 'permission_response',
+      request_id: String(requestId || ''),
+      subtype: 'error',
+      error: String(error || 'Permission denied'),
+    };
+  }
+  return {
+    type: 'permission_response',
+    request_id: String(requestId || ''),
+    subtype: 'success',
+    response: updatedInput ? { updated_input: updatedInput } : {},
+  };
+}
+
+/** A member proposes a plan; the leader approves or refuses it. */
+export function planApprovalRequest({ requestId, from, plan }) {
+  return {
+    type: 'plan_approval_request',
+    requestId: String(requestId || ''),
+    from: String(from || ''),
+    plan: String(plan || ''),
+    timestamp: new Date().toISOString(),
+  };
+}
+
+export function planApprovalResponse({ requestId, approved, feedback }) {
+  return {
+    type: 'plan_approval_response',
+    requestId: String(requestId || ''),
+    approved: Boolean(approved),
+    feedback: feedback ? String(feedback) : undefined,
+    timestamp: new Date().toISOString(),
+  };
+}
+
+/** Change a member's permission mode without restarting it. */
+export function modeSetRequest({ mode, from }) {
+  return { type: 'mode_set_request', mode: String(mode || ''), from: String(from || '') };
+}
+
+/** Correlation id for a request/response pair. */
+export function newRequestId(prefix = 'r') {
+  return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}