@hncode/hncode 0.5.1 → 0.5.4

package/src/tasks-browser.js

@@ -200,11 +200,14 @@ export function renderTasksBrowser(state, cols, rows) {
       // hitbox to aim at — those are recorded in state._taskHits below.
       const hot = state.hoverIndex === i;
       const ptr = selected ? C.cyan + '\u276f ' + C.reset : (hot ? C.hover + '\u276f ' + C.reset : '  ');
+      // A sub-task is drawn under its parent, indented, so a swarm reads as one unit of work with
+      // visible parts rather than as N unrelated rows. `parentTaskId` is set by AgentSwarm.
+      const lead = t.parentTaskId ? C.gray + '  \u2514 ' + C.reset : '';
       const idCol = t.kind === 'agent' ? C.green : t.kind === 'question' ? C.orange : C.blue;
       const idText = selected ? idCol + C.bold + t.taskId + C.reset : idCol + t.taskId + C.reset;
       const pad = ' '.repeat(Math.max(0, 20 - visWidth(t.taskId)));
       const badge = statusColorToken(t.status) + (STATUS_LABEL[t.status] || t.status) + C.reset;
-      const prefix = ptr + idText + pad + ' ' + badge;
+      const prefix = lead + ptr + idText + pad + ' ' + badge;
       const budget = Math.max(0, listInnerW - visWidth(prefix) - 1);
       if (budget < 4) return fitExactly(prefix, listInnerW);
       const desc = singleLine(t.description) || singleLine(t.command) || '(no description)';

package/src/team/constants.js

@@ -0,0 +1,20 @@
+/** The name every team's leader is known by. Not a member name a user can pick. */
+export const TEAM_LEAD_NAME = 'team-lead';
+
+/** Broadcast address in SendMessage: everyone on the team except the sender. */
+export const BROADCAST = '*';
+
+/** How many teammates one team may hold. A team that grows past this cannot be reasoned about. */
+export const MAX_TEAMMATES = 8;
+
+/** How many tool steps a teammate may take in one run before it is stopped. */
+export const TEAMMATE_MAX_STEPS = 40;
+
+/**
+ * How long a teammate waits for a message before ending its run.
+ *
+ * 0 = indefinitely, which is the default: the lead is a person typing, and a member that
+ * quits after a quiet spell cannot be given work later. A caller that genuinely wants a
+ * bounded run passes a positive value (`spawnTeammate({ idleTimeoutMs: 60_000 })`).
+ */
+export const TEAMMATE_IDLE_TIMEOUT_MS = 0;

package/src/team/context.js

@@ -0,0 +1,89 @@
+// Who is running right now.
+//
+// A teammate runs in the SAME process as its lead, so "am I a teammate" cannot live on a module
+// variable — every member would overwrite it and the last one to start would answer for all of
+// them. `AsyncLocalStorage` gives each async execution chain its own view, which is the shape
+// needed: a teammate's whole run happens inside one `runAs` call, so every function it reaches
+// sees ITS identity while the lead's sees none.
+//
+// WHY NOT A STACK
+// ---------------
+// A stack would be popped by any interleaving, and teammate runs interleave freely — they await
+// tool calls, network, timers. AsyncLocalStorage follows the async context rather than the call
+// stack, so it survives those awaits.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { TEAM_LEAD_NAME } from './constants.js';
+
+const storage = new AsyncLocalStorage();
+
+/**
+ * The identity of the member whose async context we are inside, or undefined for the lead.
+ *
+ * `undefined` IS the lead: the person at the keyboard is not a teammate. Code that needs "am I a
+ * teammate" asks `currentAgent()`, rather than a separate flag that could disagree with this.
+ */
+export function currentAgent() {
+  return storage.getStore() || undefined;
+}
+
+export function isTeammate() {
+  return !!storage.getStore();
+}
+
+/** The calling member's name, or the lead's when there is none. */
+export function currentAgentName() {
+  const ctx = storage.getStore();
+  return ctx ? ctx.name : TEAM_LEAD_NAME;
+}
+
+/** The team the calling member belongs to, or undefined for a lead with no team. */
+export function currentTeamName() {
+  const ctx = storage.getStore();
+  return ctx ? ctx.teamName : undefined;
+}
+
+/**
+ * Run `fn` as `identity`.
+ *
+ * Every await inside `fn` sees the same identity — that is the whole point, and why this must
+ * WRAP the teammate's run rather than be set before it.
+ */
+export function runAs(identity, fn) {
+  return storage.run(identity, fn);
+}
+
+/** Build the identity record for a member. */
+export function makeIdentity({ name, teamName, color, agentType, model, taskId = null }) {
+  return {
+    name,
+    teamName,
+    color,
+    agentType: agentType || 'general',
+    model: model || '',
+    // Set when this teammate was spawned to work on a specific task, so it can report back to
+    // that task rather than to the team at large.
+    taskId,
+  };
+}
+
+// Distinct enough to tell apart in a log line.
+export const MEMBER_COLORS = ['cyan', 'green', 'yellow', 'magenta', 'blue', 'red', 'orange'];
+
+/**
+ * A colour for a member: stable per name, avoiding what the team already uses.
+ *
+ * Stable because a colour that changed between messages would make the transcript unreadable —
+ * the eye tracks a member BY its colour.
+ */
+export function pickColor(name, taken = []) {
+  const used = new Set(taken);
+  const n = MEMBER_COLORS.length;
+  const start = [...String(name)].reduce((a, c) => a + c.charCodeAt(0), 0) % n;
+  for (let i = 0; i < n; i++) {
+    const c = MEMBER_COLORS[(start + i) % n];
+    if (!used.has(c)) return c;
+  }
+  // Every colour taken: share one rather than returning undefined, which would leave the member
+  // uncoloured and indistinguishable.
+  return MEMBER_COLORS[start];
+}

package/src/team/mailbox.js

@@ -0,0 +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.
+ *
+ *  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)}`;
+}