@hncode/hncode 0.4.1 → 0.5.0

package/src/subagent-control.js

@@ -0,0 +1,160 @@
+// Live control of running subagents: message one, interrupt one, close one.
+//
+// WHY A REGISTRY AND NOT A MAP ON THE AGENT
+// ----------------------------------------
+// `tools/agent.js` already keeps `subagents` (agent id -> { id, type, messages }) so a
+// `resume` can find the conversation. That map is the WRONG thing to control from: it
+// holds the RECORD of an agent, which outlives the run, while "interrupt" and "send a
+// message" need the in-flight one. A finished agent has no live handle and must not be
+// shown as controllable.
+//
+// So this module holds a SECOND map, of runs only: id -> { steer, interrupt, taskId,
+// startedAt, type, description, status }. `tools/agent.js` registers a run when it starts
+// and clears it when the run settles, which makes the registry's contents EXACTLY the set
+// of agents that can still be acted on. Nothing here guesses that from timestamps.
+//
+// The handles are the real Agent methods (`steer`, `interrupt`), so a message sent here
+// takes the same path as one the user steers into the main turn, and an interrupt stops
+// the subagent the same way Esc stops the parent — there is no second implementation to
+// drift out of step.
+
+/** runId -> live handle. Only RUNNING agents are ever in here. */
+const runs = new Map();
+
+let seq = 0;
+function nextId() {
+  seq = (seq + 1) % 1e6;
+  return `run-${Date.now().toString(36)}${String(seq).padStart(3, '0')}`;
+}
+
+/**
+ * Register a running subagent.
+ *
+ * @param {object} handle
+ * @param {string} handle.agentId     the agent id from tools/agent.js (what `resume` uses)
+ * @param {string} [handle.taskId]    the background task id, when the run was detached
+ * @param {string} handle.type        subagent type
+ * @param {string} [handle.description]
+ * @param {(text:string)=>void} handle.steer      inject a message into the running run
+ * @param {()=>void} handle.interrupt             stop the run
+ * @returns {string} the run id, for the control tools to name it
+ */
+export function registerRun(handle) {
+  const runId = nextId();
+  runs.set(runId, {
+    runId,
+    agentId: String(handle.agentId || ''),
+    taskId: handle.taskId ? String(handle.taskId) : '',
+    type: String(handle.type || ''),
+    description: String(handle.description || ''),
+    startedAt: Date.now(),
+    steer: handle.steer,
+    interrupt: handle.interrupt,
+    messages: [],
+    status: 'running',
+  });
+  return runId;
+}
+
+/** Drop a run. Called when it settles, so the registry only ever holds live work. */
+export function endRun(runId) {
+  const r = runs.get(runId);
+  if (r) r.status = 'done';
+  runs.delete(runId);
+}
+
+export function listRuns() {
+  return [...runs.values()];
+}
+
+/** Find a run by EITHER its run id or the agent id it belongs to — a caller usually has
+ *  one or the other and should not have to know which kind it holds. */
+export function findRun(ref) {
+  const key = String(ref == null ? '' : ref).trim();
+  if (!key) return null;
+  if (runs.has(key)) return runs.get(key);
+  for (const r of runs.values()) {
+    if (r.agentId === key || r.taskId === key) return r;
+  }
+  return null;
+}
+
+/**
+ * Send a message into a running subagent.
+ *
+ * `steer` rather than a new turn: the message is injected once the subagent's in-flight
+ * tool calls finish, which is the only safe point to change its instructions. A new
+ * request while tools are running would either queue behind them anyway or fork the
+ * conversation, and the second is not what "say something to this agent" means.
+ *
+ * @returns {{ok: boolean, message: string}}
+ */
+export function sendToRun(ref, text) {
+  const run = findRun(ref);
+  if (!run) return { ok: false, message: `No running subagent matches "${ref}". Use AgentMessage with no id, or TaskList, to see what is running.` };
+  const body = String(text == null ? '' : text).trim();
+  if (!body) return { ok: false, message: 'The message is empty.' };
+  try {
+    run.steer(body);
+    run.messages.push({ at: Date.now(), text: body });
+    return { ok: true, message: `Sent to ${run.agentId} (${run.type}): ${body}` };
+  } catch (e) {
+    return { ok: false, message: `Could not reach ${run.agentId}: ${e.message}` };
+  }
+}
+
+/** Stop a running subagent. Returns the agent id, so the caller can report it. */
+export function interruptRun(ref) {
+  const run = findRun(ref);
+  if (!run) return { ok: false, message: `No running subagent matches "${ref}".` };
+  try {
+    run.interrupt();
+    return { ok: true, message: `Interrupted ${run.agentId} (${run.type}).`, agentId: run.agentId, runId: run.runId };
+  } catch (e) {
+    return { ok: false, message: `Could not interrupt ${run.agentId}: ${e.message}` };
+  }
+}
+
+/** Stop every running subagent. The escape hatch when several were fanned out. */
+export function interruptAll() {
+  const all = listRuns();
+  const ids = [];
+  for (const r of all) {
+    try { r.interrupt(); ids.push(r.agentId); } catch { /* an already-dead run */ }
+  }
+  return { ok: ids.length > 0, count: ids.length, agents: ids };
+}
+
+/**
+ * Close a run: interrupt it AND forget it, so it stops appearing in listings.
+ *
+ * Distinct from interrupt on purpose. An interrupted run is removed when its `await`
+ * unwinds, which is asynchronous — so a user who interrupts and immediately lists would
+ * still see it, and would reasonably conclude the interrupt did nothing. `close` removes
+ * it at once. The record of the conversation stays in `tools/agent.js`, so `resume` still
+ * works; only the live handle goes.
+ */
+export function closeRun(ref) {
+  const run = findRun(ref);
+  if (!run) return { ok: false, message: `No running subagent matches "${ref}".` };
+  try { run.interrupt(); } catch { /* already stopping */ }
+  endRun(run.runId);
+  return { ok: true, message: `Closed ${run.agentId} (${run.type}). Its conversation stays available to \`resume\`.`, agentId: run.agentId };
+}
+
+/** Lines for a control tool / panel: one row per running subagent. */
+export function describeRuns() {
+  const all = listRuns();
+  if (!all.length) return ['No subagent is running.'];
+  const out = [`Running subagents (${all.length})`, ''];
+  for (const r of all) {
+    const secs = Math.round((Date.now() - r.startedAt) / 1000);
+    out.push(`  ${r.runId}  ${r.type.padEnd(10)} ${secs}s  ${r.agentId}`);
+    if (r.description) out.push(`      ${r.description}`);
+    if (r.messages.length) {
+      const last = r.messages[r.messages.length - 1];
+      out.push(`      last message: ${String(last.text).slice(0, 80)}`);
+    }
+  }
+  return out;
+}

package/src/tasks-browser.js

@@ -136,20 +136,47 @@ export function renderTasksBrowser(state, cols, rows) {
 
   const key = (s) => C.cyan + C.bold + s + C.reset;
   const dim = (s) => C.gray + s + C.reset;
+  // The footer doubles as a TOOLBAR: each `KEY label` pair is clickable, so the
+  // whole pair is recorded as one span. `cursor` tracks the column so the spans stay
+  // correct as the parts are concatenated by `join('  ')`.
+  const footerHits = [];
   let footer;
   if (state.pendingStop) {
-    footer = fitExactly(' ' + C.orange + C.bold + 'Stop' + C.reset + ' ' + C.white + state.pendingStop + C.reset + '? '
-      + key('Y') + ' ' + dim('confirm') + '  ' + key('N') + dim('/') + key('esc') + ' ' + dim('cancel') + ' ', cols);
+    // The confirm prompt is a toolbar too: Y / N / Esc each do something, so each
+    // gets a clickable span. `c` tracks the column so the spans land exactly on the
+    // rendered words — the original drew `N/esc cancel` as one run, so the two keys
+    // share the single "cancel" label and are measured as one span.
+    const prefix = ' ' + C.orange + C.bold + 'Stop' + C.reset + ' ' + C.white + state.pendingStop + C.reset + '? ';
+    let c = visWidth(prefix);
+    const yPart = key('Y') + ' ' + dim('confirm');
+    footerHits.push({ keyWord: 'Y', label: 'confirm', action: 'confirmStop', col0: c, col1: c + visWidth(yPart) - 1 });
+    c += visWidth(yPart) + 2;
+    const nPart = key('N') + dim('/') + key('esc') + ' ' + dim('cancel');
+    footerHits.push({ keyWord: 'N/esc', label: 'cancel', action: 'cancelStop', col0: c, col1: c + visWidth(nPart) - 1 });
+    footer = fitExactly(prefix + yPart + '  ' + nPart + ' ', cols);
   } else {
-    const parts = [
-      ' ' + key('\u2191\u2193') + ' ' + dim('select'),
-      key('Enter/O') + ' ' + dim('output'),
-      key('S') + ' ' + dim('stop'),
-      key('R') + ' ' + dim('refresh'),
-      key('Tab') + ' ' + dim('filter'),
-      key('Q/Esc') + ' ' + dim('close') + ' ',
+    const specs = [
+      ['\u2191\u2193', 'select', 'select'],
+      ['Enter/O', 'output', 'openOutput'],
+      ['S', 'stop', 'requestStop'],
+      ['R', 'refresh', 'refresh'],
+      ['Tab', 'filter', 'toggleFilter'],
+      ['Q/Esc', 'close', 'close'],
     ];
-    const left = parts.join('  ');
+    const parts = [];
+    let cursor = 1;
+    for (const [kw, label, action] of specs) {
+      const piece = key(kw) + ' ' + dim(label);
+      const w = visWidth(piece);
+      // `col1` is the LAST included column (hitboxes use an inclusive range, see
+      // hitAt), so a piece starting at `cursor` spanning `w` cells ends at
+      // `cursor + w - 1`. Using `cursor + w` made the span one column too wide, so a
+      // hover tinted the following space as well.
+      footerHits.push({ keyWord: kw, label, action, col0: cursor, col1: cursor + w - 1 });
+      cursor += w + 2;             // the `parts.join('  ')` separator
+      parts.push(piece);
+    }
+    const left = ' ' + parts.join('  ');
     const flash = state.flash ? C.orange + ' ' + state.flash + ' ' + C.reset : '';
     const total = visWidth(left) + visWidth(flash);
     footer = total <= cols ? left + ' '.repeat(cols - total) + flash : fitExactly(left, cols);
@@ -168,7 +195,11 @@ export function renderTasksBrowser(state, cols, rows) {
   } else {
     listLines = visible.map((t, i) => {
       const selected = i === state.selectedIndex;
-      const ptr = selected ? C.cyan + '\u276f ' + C.reset : '  ';
+      // Hover highlight, mirroring the rest of the TUI: the row under the pointer is
+      // tinted by the generic hover pass in tui.js (composeFrame), which needs a
+      // 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 : '  ');
       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)));
@@ -180,6 +211,18 @@ export function renderTasksBrowser(state, cols, rows) {
       return fitExactly(prefix + ' ' + C.white + truncateToWidth(desc, budget) + C.reset, listInnerW);
     });
   }
+  // Click targets. Coordinates are FRAME cells: line 0 is the header, line 1 is the
+  // list box's TOP RULE, so the first content row is line 2 — using `1 + i` put the
+  // hitboxes one row high, which highlighted the border instead of the task and made
+  // a click select the wrong row. Columns match the box interior (`│` + 1 cell of
+  // padding), and `col1` is the LAST included column.
+  state._taskHits = [];
+  for (let i = 0; i < Math.min(visible.length, listInnerH); i++) {
+    state._taskHits.push({ row: 2 + i, col0: 1, col1: listInnerW, kind: 'taskRow', index: i });
+  }
+  for (const h of footerHits) {
+    state._taskHits.push({ row: rows - 1, col0: h.col0, col1: h.col1, kind: 'taskFooter', action: h.action });
+  }
   while (listLines.length < listInnerH) listLines.push('');
   const listFrame = renderFrame('Tasks [' + state.filter + ']', listLines.slice(0, listInnerH), listW, bodyH);
 

package/src/teleport.js

@@ -0,0 +1,260 @@
+// Session teleport — carry a conversation to another machine or another checkout.
+//
+// Why not just copy the session file: a session's JSON contains absolute paths (the
+// workspace, every file the tools touched) and the tool arguments that name them. A
+// file teleported verbatim to a different checkout resumes with a workspace that
+// does not exist and a transcript full of paths that resolve to nothing. So a
+// teleport is a TRANSFORM, not a copy:
+//
+//   * paths under the old workspace are rewritten to the new one;
+//   * the workspace itself is recorded, so the receiving side can check it exists;
+//   * everything machine-specific that would be WRONG on the other machine is
+//     dropped rather than carried (see `stripVolatile`).
+//
+// The container is plain JSON with a small header, so a teleport can be inspected,
+// edited by hand, or piped through `ssh`. Compression is deliberately not used: a
+// session is text, base64 would make it unreadable, and the transport (scp, ssh,
+// git) can compress better than we can.
+
+/** The header written into every teleport file, so a stale format is detectable. */
+export const TELEPORT_FORMAT = 'hncode-teleport';
+export const TELEPORT_VERSION = 1;
+
+/**
+ * Fields that describe THIS machine's runtime rather than the conversation. Carried
+ * verbatim they would be wrong on the other side in a way that looks like data
+ * corruption, so they are dropped: a running tool's live output refers to a process
+ * that no longer exists, and the token/cost totals belong to the machine that spent
+ * them.
+ */
+const VOLATILE_KEYS = [
+  'tasks',              // background jobs: the processes are gone
+  'usage',              // token totals spent on the exporting machine
+  'sessionApprovals',   // grants the user made here must not transfer silently
+  '_tokTimes',
+  '_metrics',
+];
+
+/** Drop the machine-specific fields, returning a copy. */
+export function stripVolatile(session) {
+  const out = { ...(session || {}) };
+  for (const k of VOLATILE_KEYS) delete out[k];
+  // A live or pending tool row belongs to a turn that is not running here.
+  if (Array.isArray(out.messages)) {
+    out.messages = out.messages.map((m) => {
+      if (!m || typeof m !== 'object') return m;
+      const c = { ...m };
+      delete c.pending;
+      delete c.liveOutput;
+      return c;
+    });
+  }
+  return out;
+}
+
+/** Normalise a path to forward slashes with no trailing separator, for comparison. */
+function norm(p) {
+  return String(p == null ? '' : p).replace(/\\/g, '/').replace(/\/+$/, '');
+}
+
+/**
+ * Rewrite the paths under `from` to `to`, anywhere in the session.
+ *
+ * A STRUCTURAL walk over the parsed object, not a text replace over the serialized
+ * JSON. The text approach looked simpler but could never work on Windows: JSON
+ * escapes a backslash as `\\`, so the string `D:\old\proj` appears in the file as
+ * `D:\\old\\proj` and searching for the raw path finds nothing. Escaping the search
+ * term to match produced a second class of misses (a path that legitimately contains
+ * a backslash next to text that is not part of it).
+ *
+ * Walking every string compares the path in its NORMALISED form (forward slashes, no
+ * trailing separator), so `D:\old\proj`, `D:/old/proj` and a trailing-slash variant
+ * all match, and the REPLACEMENT is written back in the separator style the original
+ * string used — a Windows session keeps backslashes, a POSIX one keeps slashes.
+ */
+export function rewriteWorkspace(session, from, to) {
+  const oldPath = norm(from);
+  const newPath = norm(to);
+  if (!oldPath || !newPath || oldPath === newPath) return session;
+  const walk = (value) => {
+    if (typeof value === 'string') return replaceInString(value, oldPath, newPath);
+    if (Array.isArray(value)) return value.map(walk);
+    if (value && typeof value === 'object') {
+      const out = {};
+      for (const [k, v] of Object.entries(value)) out[k] = walk(v);
+      return out;
+    }
+    return value;
+  };
+  return walk(session);
+}
+
+/**
+ * Replace `oldPath` inside one string, preserving the separator style.
+ *
+ * The match is done on a normalised COPY of the string with index mapping, so the
+ * replacement lands in the right place while the surrounding text is untouched. A
+ * simple `split/join` on the normalised form would rewrite every backslash in the
+ * string, including ones that are not path separators.
+ */
+function replaceInString(text, oldPath, newPath) {
+  const normText = norm(text);
+  // The whole-string case is by far the most common (a path ARGUMENT). The tail may
+  // carry a trailing separator the normalisation removed, which is dropped with it:
+  // `D:\old\proj\` becomes the new path, not the new path plus a stray slash.
+  if (normText === oldPath) return toStyle(newPath);
+  return replaceByIndex(text, oldPath, newPath);
+}
+
+// Replace every path-shaped occurrence, matching on the normalised form and writing
+// the replacement at the ORIGINAL indices. norm() rewrites separators one character
+// for one, so the indices line up exactly and the surrounding text is never touched.
+//
+// The replacement extends past the matched prefix to the END OF THE PATH TOKEN, and
+// the tail is re-emitted with POSIX separators. Without that, moving a Windows
+// checkout to Linux produced `read /home/me/proj\src\a.js` — the prefix rewritten and
+// the rest still using backslashes, which resolves on neither system.
+function replaceByIndex(text, oldPath, newPath) {
+  const normText = norm(text);
+  let at = normText.indexOf(oldPath);
+  if (at < 0) return text;
+  const styled = toStyle(newPath);
+  let out = '';
+  let cursor = 0;
+  while (at >= 0) {
+    const before = at === 0 ? '' : text[at - 1];
+    const end = at + oldPath.length;
+    const after = end >= text.length ? '' : text[end];
+    // Only a path-SHAPED hit counts, so a coincidental substring inside a word is
+    // left alone. `okAfter` has to accept a separator too: the match may stop at the
+    // workspace root while the string continues into a file (`…/proj/src/a.js`).
+    const okBefore = at === 0 || /[\\/\s"'(=,:;]/.test(before);
+    const okAfter = end >= text.length || /[\\/\s"'),:;]/.test(after);
+    if (okBefore && okAfter) {
+      // Consume the rest of the path token so its separators can be normalised too.
+      let stop = end;
+      const sep = /[\\/]/;
+      if (end < text.length && sep.test(text[end])) {
+        while (stop < text.length && !/[\s"'),:;]/.test(text[stop])) stop++;
+      }
+      out += text.slice(cursor, at) + styled + toStyle(text.slice(end, stop));
+      cursor = stop;
+      at = normText.indexOf(oldPath, stop);
+      continue;
+    }
+    at = normText.indexOf(oldPath, at + 1);
+  }
+  return out + text.slice(cursor);
+}
+
+/**
+ * Write `p` with POSIX separators.
+ *
+ * Always forward slashes, whatever the input string used: the target workspace is
+ * what decides the style, and the target is recorded POSIX-normalised (see pack). A
+ * Windows SOURCE path that lands on a Linux checkout must come out as `/home/x/proj`,
+ * not `\home\x\proj`, or the receiving side resolves nothing.
+ */
+function toStyle(p) {
+  return String(p).replace(/\\/g, '/');
+}
+
+/**
+ * Build the teleport container for a session.
+ *
+ * `opts.from` / `opts.to` rewrite the workspace; `to` is also recorded as the
+ * workspace the receiving side should have.
+ */
+export function packSession(session, opts = {}) {
+  const from = opts.from || session.workspace || '';
+  const to = opts.to || from;
+  const body = rewriteWorkspace(stripVolatile(session), from, to);
+  return {
+    format: TELEPORT_FORMAT,
+    version: TELEPORT_VERSION,
+    exportedAt: new Date().toISOString(),
+    // The workspace the session EXPECTS. The importing side checks this and reports
+    // a mismatch rather than silently resuming somewhere else.
+    workspace: norm(to),
+    // Recorded so the importer can show what happened, and a human reviewing the
+    // file can see it moved.
+    from: norm(from),
+    title: body.title || '',
+    rounds: body.rounds || 0,
+    session: { ...body, workspace: norm(to) },
+  };
+}
+
+/** Serialize a teleport for writing. */
+export function serializeTeleport(pack) {
+  return JSON.stringify(pack, null, 2) + '\n';
+}
+
+/**
+ * Parse and validate a teleport. Throws with a specific reason, because the common
+ * failure is pasting the wrong file and "invalid JSON" alone does not say that.
+ */
+export function parseTeleport(text) {
+  let pack;
+  try { pack = JSON.parse(String(text || '')); }
+  catch (e) { throw new Error(`not valid JSON: ${e.message}`); }
+  if (!pack || typeof pack !== 'object') throw new Error('empty teleport');
+  if (pack.format !== TELEPORT_FORMAT) {
+    throw new Error(`not an hncode teleport (format is ${JSON.stringify(pack.format)})`);
+  }
+  if (!(pack.version <= TELEPORT_VERSION)) {
+    throw new Error(`teleport version ${pack.version} is newer than this build (${TELEPORT_VERSION})`);
+  }
+  if (!pack.session || typeof pack.session !== 'object') throw new Error('teleport has no session');
+  return pack;
+}
+
+/**
+ * Prepare an imported teleport for this machine.
+ *
+ * Returns `{ session, warnings }`. Warnings rather than errors: a renamed checkout is
+ * a common, recoverable situation, and refusing to import would strand the
+ * conversation. The caller decides whether to continue.
+ */
+export function unpackInto(pack, opts = {}) {
+  const warnings = [];
+  const here = norm(opts.workspace || pack.workspace || '');
+  const there = norm(pack.workspace || '');
+  if (there && here && there !== here) {
+    warnings.push(`the session was recorded in ${there}, but this workspace is ${here} — paths have been rewritten`);
+  }
+  let session = pack.session;
+  // Re-point at THIS workspace when it differs, so the transcript's paths resolve.
+  session = rewriteWorkspace(session, there, here);
+  // A fresh id unless the caller wants the original: importing twice under one id
+  // would make the two copies overwrite each other on save.
+  session = { ...session, workspace: here, importedAt: new Date().toISOString() };
+  if (opts.newId && typeof opts.newId === 'function') session.id = opts.newId();
+  return { session, warnings };
+}
+
+/** `hncode-teleport-<id>-<stamp>.json`, a name that sorts by time and names the origin. */
+export function teleportFileName(session, at = new Date()) {
+  const id = String((session && session.id) || 'session').replace(/[^A-Za-z0-9_-]/g, '').slice(0, 24) || 'session';
+  const stamp = at.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  return `hncode-teleport-${id}-${stamp}.json`;
+}
+
+/** A human summary for the confirmation message. */
+export function describeTeleport(pack) {
+  const msgs = Array.isArray(pack.session && pack.session.messages) ? pack.session.messages.length : 0;
+  return [
+    `title      ${pack.title || '(untitled)'}`,
+    `from       ${pack.from || '(unknown)'}`,
+    `workspace  ${pack.workspace || '(unknown)'}`,
+    `exported   ${pack.exportedAt || '(unknown)'}`,
+    `messages   ${msgs}`,
+    `rounds     ${pack.rounds || 0}`,
+  ].join('\n');
+}
+
+export default {
+  packSession, serializeTeleport, parseTeleport, unpackInto,
+  rewriteWorkspace, stripVolatile, teleportFileName, describeTeleport,
+  TELEPORT_FORMAT, TELEPORT_VERSION,
+};