@hncode/hncode 0.5.2 → 0.5.5

package/src/team/runner.js

@@ -186,12 +186,19 @@ export function teammateSystemPrompt(team, member) {
 export async function waitForMail(teamName, agentName, { timeoutMs = 0, pollMs = 250, shouldStop } = {}) {
   const forever = !(timeoutMs > 0);
   const deadline = forever ? Infinity : Date.now() + timeoutMs;
+  // Back off while the box stays empty: 250ms -> 2s. Every poll is a readFileSync
+  // plus a JSON.parse of the whole inbox, so an idle eight-member team burned
+  // 32 sync file reads a second, forever. Delivery is still prompt — a message
+  // lands at most one backoff step (~2s) late, which is imperceptible for a
+  // person typing the next instruction.
+  let wait = pollMs;
   for (;;) {
     if (shouldStop && shouldStop()) return null;
     const unread = readUnread(teamName, agentName);
     if (unread.length) return unread;
     if (Date.now() >= deadline) return null;
-    await new Promise((r) => setTimeout(r, pollMs));
+    await new Promise((r) => setTimeout(r, wait));
+    wait = Math.min(wait * 2, 2000);
   }
 }
 
@@ -215,6 +222,18 @@ export async function runTeammate({
   makeAgent,
   onStart,
   onFinish,
+  // Live output from this member's turn: `{ kind, text }` / `{ kind: 'tool', name, detail }`.
+  //
+  // Without it a teammate was a black box — the roster said idle→working→idle and nothing about what
+  // it did in between. A person watching a team needs to see the work, not only its conclusion: a
+  // member that spends forty seconds running tests looks identical to one that hung.
+  onStream = () => {},
+  // Ask the person before a tool runs, via the lead's mailbox.
+  // `async (toolName, args) => boolean | { approved, error }`.
+  //
+  // An injected hook rather than a hard-wired call: `runTeammate` is exercised in tests with a fake agent
+  // and no team, and a permission round-trip there would block for the full timeout on every tool.
+  askPermission,
 }) {
   const identity = currentAgent();
   if (!identity || identity.name !== memberName) {
@@ -243,18 +262,22 @@ export async function runTeammate({
   // The system entry goes FIRST and the task text after it. The Agent has no `systemPrompt`
   // option — the prompt is an ordinary system message the caller supplies, which is how the
   // TUI builds one per turn.
+  //
+  // THE FIRST PROMPT MUST NOT BE EMPTY. An empty user turn gives the model nothing to answer, so the
+  // round produces no reply and the member looks dead. That happened whenever `firstPrompt` had nothing
+  // to say — no task, no assignment, and no lead to report to — which is the NORMAL start for the first
+  // member of a team, because `addMember` makes the first member the lead and "report to the lead" then
+  // resolves to itself and returns ''.
+  const opening = firstPrompt({
+    team,
+    member,
+    task,
+    taskList: taskList.length ? taskList.map((t) => `${t.id} ${t.status} ${t.subject}`).join('\n') : '',
+    assignment: member.prompt || '',
+  }) || 'You are on the team and have no task yet. Read the messages in your next input, answer the lead, and use SendMessage to reply.';
   const messages = [
     { role: 'system', content: teammateSystemPrompt(team, member) },
-    {
-      role: 'user',
-      content: firstPrompt({
-        team,
-        member,
-        task,
-        taskList: taskList.length ? taskList.map((t) => `${t.id} ${t.status} ${t.subject}`).join('\n') : '',
-        assignment: member.prompt || '',
-      }),
-    },
+    { role: 'user', content: opening },
   ];
 
   onStart && onStart({ member, task });
@@ -272,21 +295,113 @@ export async function runTeammate({
     // One round of the teammate's work. `makeAgent` is injectable so the loop can be tested
     // without a model; production passes nothing and gets a real Agent.
     const build = makeAgent || ((opts) => new Agent(opts));
+    // Whether THIS round invoked SendMessage. Reset per round because the fallback below only applies
+    // to a round that stayed silent — a member that answered with the tool has already been delivered.
+    let sentThisRound = false;
     const agent = build({
       cfg,
       messages,
       maxSteps: TEAMMATE_MAX_STEPS,
+      // ASK THE PERSON, THROUGH THE LEAD, BEFORE ANY TOOL RUNS.
+      //
+      // A teammate can write files and run commands, and until this existed it had exactly two options:
+      // do anything, or be unable to ask. This forwards the question to the lead's mailbox and BLOCKS
+      // here until the answer comes back — the runner is synchronous per round, so a refusal has to
+      // arrive as a value, not as a later event.
+      //
+      // `askPermission` is undefined for a team whose lead has no panel; the call then resolves to a
+      // refusal with a reason, which the model can act on.
+      onApproval: askPermission,
       onEvent: (e) => {
+        if (e.type === 'tool_start' && /^SendMessage$/.test(String(e.name || ''))) sentThisRound = true;
         if (e.type === 'tool_start') toolNote(memberName, e.name, e.args);
         // The one moment a member is unambiguously working, as opposed to blocked on the
         // model — which is what most of a round is.
         updateMember(teamName, memberName, { isActive: true, phase: 'working' });
+
+        // LIVE OUTPUT — as TRANSCRIPT ENTRIES, not status blips.
+        //
+        // Claude Code renders a teammate by feeding `viewedAgentTask.messages` to the SAME <Messages>
+        // component the main transcript uses (REPL.tsx: `displayedMessages = viewedAgentTask.messages`),
+        // so its answer, its tool calls and their results read as one conversation. Relaying bare
+        // strings meant the panel had nothing to show but a single activity line — which is exactly the
+        // complaint: "I switch to a member and see no messages, though it is working."
+        try {
+          if (e.type === 'data' && e.text) {
+            onStream({ kind: 'text', name: memberName, text: String(e.text) });
+          } else if (e.type === 'think' && e.text) {
+            onStream({ kind: 'think', name: memberName, text: String(e.text) });
+          } else if (e.type === 'tool_start') {
+            onStream({ kind: 'tool', name: memberName, tool: String(e.name || ''), id: e.id || '' });
+          } else if (e.type === 'tool_result') {
+            // The WHOLE result. The panel wraps and clips at render time, where the available height is
+            // known; trimming to the first line here threw away the body a reader came for.
+            onStream({
+              kind: 'tool_result',
+              name: memberName,
+              tool: String(e.name || ''),
+              id: e.id || '',
+              detail: String(e.content || ''),
+              editDiff: e.editDiff || null,
+            });
+          }
+        } catch { /* a display hook must never fail a member's turn */ }
       },
     });
-    await agent.run();
+    // A ROUND THAT THROWS MUST BE REPORTED, not swallowed.
+    //
+    // `agent.run()` reaches the model, so it fails for every reason the network and the provider can
+    // produce: no model configured, a bad key, a 429, a dropped connection. Without this the error left
+    // `runTeammate` entirely — no reply, no log the user could see, and the member simply looked
+    // unresponsive. That is indistinguishable from "the team is ignoring me", which is exactly how it was
+    // reported.
+    //
+    // The message goes to the lead's inbox, which reaches the TUI through the same onLeadMail path as an
+    // ordinary reply, so a failure is visible where a reply would have been.
+    try {
+      await agent.run();
+    } catch (e) {
+      const why = (e && e.message) || String(e);
+      writeToMailbox(teamName, TEAM_LEAD_NAME, {
+        from: memberName,
+        text: `I could not complete this round: ${why}`,
+        summary: 'round failed',
+        color: member.color,
+      });
+      result.failed = (result.failed || 0) + 1;
+      result.lastError = why;
+      updateMember(teamName, memberName, { isActive: false, phase: 'idle' });
+      onFinish && onFinish({ member, task });
+      result.ok = false;
+      // Back to waiting rather than exiting: a transient failure (a rate limit) must not end the member.
+      // `waitForMail` below decides whether it stops, on the same terms as a successful round.
+      const mail = await waitForMail(teamName, memberName, { timeoutMs: idleTimeoutMs, shouldStop });
+      if (!mail) { idle = true; break; }
+      continue;
+    }
 
     // The Agent kept the SAME array and appended to it, so the transcript already carries
     // this round. Nothing to copy — `messages` IS `agent.messages`.
+    // A round that answered in TEXT instead of calling SendMessage must still reach the lead.
+    //
+    // The tool is how a member is TOLD to reply, and most rounds use it. A model that answers
+    // conversationally instead — "I'm here, got your message" — produces the same words and sends them
+    // nowhere, so the person who asked gets silence while the member considers itself done. From outside
+    // that is indistinguishable from being ignored, which is how it was reported.
+    //
+    // The guard: only when `SendMessage` did NOT run this round. `sentThisRound` is set by the agent's
+    // tool events, so a round that replied properly is not answered twice.
+    if (!sentThisRound) {
+      const text = lastAssistantText(agent);
+      if (text) {
+        writeToMailbox(teamName, TEAM_LEAD_NAME, {
+          from: memberName,
+          text,
+          summary: 'reply',
+          color: member.color,
+        });
+      }
+    }
 
     // A tool named SendMessage already delivered its message (see the tool's own handler), so
     // here we only report completion to the lead if the agent did not.

package/src/team/spawn.js

@@ -15,7 +15,22 @@ import { runTeammate } from './runner.js';
 import { addMember, setMemberActive } from './team.js';
 import { updateMember } from './store.js';
 import { readTeamFile } from './store.js';
-import { TEAMMATE_MAX_STEPS } from './constants.js';
+import { TEAMMATE_MAX_STEPS, TEAM_LEAD_NAME } from './constants.js';
+import { requestPermission } from './permission.js';
+import { leadOf } from './team.js';
+
+/**
+ * One line describing what a tool call would do, for the permission prompt.
+ *
+ * A tool NAME tells the person nothing — "Bash" could be `ls` or `rm -rf`. These are the fields Claude
+ * Code checks, in the same order, because they are what the common tools put their intent in.
+ */
+function describeCall(toolName, args) {
+  const a = args && typeof args === 'object' ? args : {};
+  const desc = a.description || a.command || a.prompt || a.query || a.pattern || a.file_path || a.path;
+  if (desc) return String(desc).split('\n')[0].slice(0, 120);
+  return `${toolName} with no description`;
+}
 
 /** Live teammates, by agent id. The abort handle and the running promise. */
 const running = new Map();
@@ -51,7 +66,14 @@ export function spawnTeammate({
   maxSteps = TEAMMATE_MAX_STEPS,
   cwd,
   onEvent,
+  // Called when this teammate sends a message to the lead — that is, to the person using hncode. The
+  // TUI passes one so the text lands in their transcript as it is sent; see `SendMessage` for what went
+  // wrong without it.
+  onLeadMail,
   tasks,
+  // 'ask' installs the permission round trip (see below). Anything else leaves the member able to
+  // run tools unattended — what a headless spawn wants.
+  permissionMode = '',
 }) {
   const team = readTeamFile(teamName);
   if (!team) return { ok: false, error: `no team "${teamName}"` };
@@ -107,6 +129,10 @@ export function spawnTeammate({
     abort() { abort.aborted = true; for (const l of abort.listeners) { try { l(); } catch { /* best effort */ } } },
     get signal() { return abort; },
   };
+  // TaskStop reaches a teammate through this handle. Without it the task had
+  // neither `_abort` nor `pid`, so a stop settled the task as 'killed' while
+  // the member kept polling its inbox forever.
+  task._abort = () => controller.abort();
 
   appendTaskOutput(task, `[${name}] started on team "${teamName}"\n`);
   onEvent && onEvent({ type: 'start', name, teamName, taskId: task.taskId, color: member.color });
@@ -120,6 +146,10 @@ export function spawnTeammate({
   const runCfg = {
     ...cfg,
     model: member.model || cfg.subagentModel || cfg.model,
+    // Carried on the config so the teammate's own `SendMessage` can reach the TUI. This is the
+    // channel that makes a reply appear in the user's transcript the moment it is sent, instead of
+    // waiting for their next turn (see the tool's handler for what went wrong without it).
+    onLeadMail,
   };
   let ok = false;
   const promise = runAs(identity, async () => {
@@ -138,6 +168,30 @@ export function spawnTeammate({
         shouldStop: () => abort.aborted,
         onStart: () => onEvent && onEvent({ type: 'working', name }),
         onFinish: () => onEvent && onEvent({ type: 'idle', name }),
+        // Relay the member's live output upward. The UI decides what to do with it; spawning only
+        // carries it, which keeps the display policy in one place.
+        onStream: (s) => onEvent && onEvent({ type: 'stream', name, stream: s }),
+        // THE PERMISSION ROUND TRIP: the member blocks here until the person answers through the lead's
+        // mailbox, and `requestPermission` polls for the matching `request_id`.
+        //
+        // Only installed when someone can actually answer — a headless spawn has no panel, and blocking
+        // for ten minutes on a question nobody can see would look like a hang.
+        askPermission: permissionMode === 'ask'
+          ? async (toolName, args) => {
+            const lead = leadOf(teamName) || TEAM_LEAD_NAME;
+            const verdict = await requestPermission({
+              teamName,
+              memberName: name,
+              leadName: lead,
+              toolName,
+              description: describeCall(toolName, args),
+              input: args && typeof args === 'object' ? args : {},
+              shouldStop: () => abort.aborted,
+            });
+            onEvent && onEvent({ type: 'permission', name, toolName, approved: verdict.approved });
+            return verdict;
+          }
+          : undefined,
       });
       ok = true;
       appendTaskOutput(task, `[${name}] finished${result.idle ? ' (idle timeout)' : ''}\n`);
@@ -177,9 +231,6 @@ export function spawnTeammate({
     teamName,
     taskId: task.taskId,
     controller,
-    teamName,
-    taskId: task.taskId,
-    controller,
     promise,
     color: member.color,
   });
@@ -197,7 +248,14 @@ export function spawnMany(teamName, members, opts) {
   const started = [];
   const failed = [];
   for (const m of members) {
-    const r = spawnTeammate({ teamName, cwd: opts.cwd, cfg: opts.cfg, toolNote: opts.toolNote, onEvent: opts.onEvent, ...m });
+    const r = spawnTeammate({
+      teamName, cwd: opts.cwd, cfg: opts.cfg, toolNote: opts.toolNote, onEvent: opts.onEvent,
+      onLeadMail: opts.onLeadMail,
+      // Carried through from the caller. `ask` installs the permission round trip; anything else leaves
+      // the member able to run tools unattended, which is what a headless spawn wants.
+      permissionMode: opts.permissionMode,
+      ...m,
+    });
     if (r.ok) started.push({ name: m.name, taskId: r.taskId });
     else failed.push({ name: m.name, error: r.error });
   }

package/src/team/store.js

@@ -76,19 +76,46 @@ export function listTeams() {
   return out.sort((a, b) => (b.createdAt || 0) - (a.createdAt || 0));
 }
 
-/** The roster, or null. Never throws. */
+/** The roster, or null. Never throws.
+ *
+ *  Cached by (mtimeMs, size): the team panel renders this on EVERY frame, and a
+ *  readFileSync + JSON.parse per frame sat in the hottest path there is. A stat
+ *  per frame replaces the full read; any write (tmp+rename) changes the mtime,
+ *  so nothing stale survives. */
+let _teamCache = { key: '', team: null };
 export function readTeamFile(teamName) {
+  const file = teamFilePath(teamName);
+  let st = null;
+  try { st = fs.statSync(file); } catch { /* absent */ }
+  if (!st) return null;
+  const key = `${file}:${st.mtimeMs}:${st.size}`;
+  if (_teamCache.key === key) return _teamCache.team;
   try {
-    return JSON.parse(fs.readFileSync(teamFilePath(teamName), 'utf8'));
+    const team = JSON.parse(fs.readFileSync(file, 'utf8'));
+    _teamCache = { key, team };
+    return team;
   } catch {
+    _teamCache = { key: '', team: null };
     return null;
   }
 }
 
-/** Write the roster, creating the directory. Throws only on a real IO failure. */
+/** Write the roster, creating the directory. Throws only on a real IO failure.
+ *
+ *  Atomic (tmp + rename), like every other team write: a plain writeFileSync
+ *  dying mid-write left a truncated config.json, and readTeamFile then returned
+ *  null — the whole team silently disappeared. */
 export function writeTeamFile(teamName, teamFile) {
   fs.mkdirSync(teamDir(teamName), { recursive: true });
-  fs.writeFileSync(teamFilePath(teamName), JSON.stringify(teamFile, null, 2), 'utf8');
+  const target = teamFilePath(teamName);
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(teamFile, null, 2), 'utf8');
+  try {
+    fs.renameSync(tmp, target);
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch { /* nothing more to do */ }
+    throw e;
+  }
   return teamFile;
 }
 

package/src/team/tasks.js

@@ -37,11 +37,24 @@ function writeAtomic(file, text) {
 }
 
 /** Every task, oldest first. Never throws. */
+// Cached by (mtimeMs, size) — the team panel reads the task list every frame,
+// and a stat per read replaces the full readFileSync + JSON.parse. writeTasks
+// goes through writeAtomic (rename), which always changes the mtime.
+let _tasksCache = { key: '', tasks: null };
 export function readTasks(teamName) {
+  const file = tasksFile(teamName);
+  let st = null;
+  try { st = fs.statSync(file); } catch { /* absent */ }
+  if (!st) return [];
+  const key = `${st.mtimeMs}:${st.size}`;
+  if (_tasksCache.key === key) return _tasksCache.tasks.slice();
   try {
-    const parsed = JSON.parse(fs.readFileSync(tasksFile(teamName), 'utf8'));
-    return Array.isArray(parsed) ? parsed : [];
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const tasks = Array.isArray(parsed) ? parsed : [];
+    _tasksCache = { key, tasks };
+    return tasks.slice();
   } catch {
+    _tasksCache = { key: '', tasks: null };
     return [];
   }
 }

package/src/team/team.js

@@ -69,21 +69,29 @@ export function addMember(teamName, { name, agentType = 'general', model = '', t
     return { ok: false, error: `team "${teamName}" already has ${others.length} members (max ${MAX_TEAMMATES})` };
   }
 
-  // THE FIRST MEMBER IS THE LEAD.
-  //
-  // A team with no leader is not a team — nothing can be reported TO — so the first member takes
-  // the role, and the team records its name and id. Every later member is a peer.
-  const isFirst = team.members.length === 0;
+  // One sanitized name is one inbox FILE: `Bob` and `bob`, or `a-b` and `a_b`,
+  // fold to the same path and would silently SHARE a mailbox, receiving each
+  // other's mail. A new member whose folded name collides with an existing one
+  // is refused — the caller picks a distinct name instead.
+  const folded = sanitizeName(memberName);
+  const clash = others.find((m) => sanitizeName(m.name) === folded);
+  if (clash) {
+    return { ok: false, error: `"${memberName}" folds to the same mailbox file as "${clash.name}" — pick a name that differs beyond case, dashes and underscores` };
+  }
 
   const color = pickColor(memberName, others.map((m) => m.color));
   const member = {
     agentId: formatAgentId(memberName, teamName),
     name: memberName,
     agentType,
-    // RANK, not trade. `agentType` says what a member does; this says where it sits. Kept as a
-    // field rather than derived from the name, so a lead can be renamed and a team can name its
-    // own leader.
-    role: isFirst ? 'lead' : 'member',
+    // RANK, not trade. `agentType` says what a member does; this says where it sits.
+    //
+    // ALWAYS `member`. The first person added was made `lead`, on the reasoning that a team with no
+    // leader is not a team — but that got it backwards for the only caller there is: `/team add`
+    // recruits someone to DO the work, and the person typing is already in charge. Labelling the first
+    // recruit a lead made it believe nobody had assigned it anything and that no message could have
+    // arrived, which is exactly what it then reported.
+    role: 'member',
     model,
     color,
     joinedAt: Date.now(),
@@ -95,10 +103,6 @@ export function addMember(teamName, { name, agentType = 'general', model = '', t
     // time blocked on the model, and a member that has never run is not working either.
     phase: 'starting',
   };
-  if (isFirst) {
-    team.leadName = memberName;
-    team.leadAgentId = member.agentId;
-  }
   team.members = [...others, member];
   writeTeamFile(teamName, team);
   return { ok: true, member };
@@ -166,6 +170,27 @@ export function findMember(teamName, name) {
   return team.members.find((m) => m.name === name) || null;
 }
 
+/**
+ * Record a member's permission mode: `ask` | `auto` | `yolo`.
+ *
+ * Stored on the roster rather than broadcast as a message, because the mode is a property of the member
+ * that has to survive a restart — a respawn reads it here. A running member keeps the hook it was built
+ * with, so a change takes effect next time it starts; that is stated in the panel's flash message rather
+ * than left to surprise someone.
+ *
+ * `ask` is the default and the safe one: every tool call is a question. `auto` and `yolo` run without
+ * asking, which is what makes them worth an explicit, per-member switch.
+ */
+export function setMemberMode(teamName, name, mode) {
+  const team = readTeamFile(teamName);
+  if (!team) return false;
+  const m = team.members.find((x) => x.name === name);
+  if (!m) return false;
+  m.permissionMode = String(mode || 'ask');
+  writeTeamFile(teamName, team);
+  return true;
+}
+
 /** Everyone except `except`, used for broadcast. */
 export function otherMembers(teamName, except) {
   const team = readTeamFile(teamName);
@@ -234,7 +259,7 @@ export function readLeadInbox(teamName) {
     for (const m of readUnread(teamName, n)) {
       // Skip the USER'S OWN sends. Every message the user writes from the panel or `/team msg` is
       // stamped `from: TEAM_LEAD_NAME`, so it must not come back as mail from the team: typing
-      // "你好" to the lead and being handed `team-lead: 你好` as unread team traffic is the model
+      // "hello" to the lead and being handed `team-lead: hello` as unread team traffic is the model
       // reading the person's own instruction as though an agent had sent it.
       //
       // The test is the SENDER being the alias — NOT the lead being the user. The lead is a
@@ -271,8 +296,18 @@ export function formatLeadInbox(teamName, { mark = false } = {}) {
   const unread = readLeadInbox(teamName);
   if (!unread.length) return '';
   if (mark) markLeadInboxRead(teamName, unread);
-  const body = unread.map((m) => `${m.from}: ${String(m.text || '').trim()}`).join('\n');
-  return `${unread.length} unread message(s) for the team lead. Answer with the SendMessage tool.\n\n${body}`;
+  // One block per message, delimited.
+  //
+  // Joined with nothing but a newline, two messages from the same sender read as one wall of text: a
+  // reply that happens to begin with a number was indistinguishable from a list index, which is exactly
+  // how "1: ..." twice in a row looked like broken numbering rather than two separate answers.
+  const body = unread
+    .map((m) => {
+      const who = String(m.from || 'unknown');
+      return `--- from ${who} ---\n${String(m.text || '').trim()}`;
+    })
+    .join('\n\n');
+  return `${unread.length} unread message(s) for the team lead. Answer each with the SendMessage tool.\n\n${body}`;
 }
 
 export function readRoster(teamName) {