@hncode/hncode 0.5.1 → 0.5.4

package/src/session-core.js

@@ -0,0 +1,203 @@
+// The session, as a thing a non-TUI front end can own.
+//
+// WHY NOT MOVE THE FIELDS
+// -----------------------
+// `state` already IS the session state — `chat`, `queued`, `running`, `rounds`, `steps`, `todos`,
+// `ctxTokens`, `workMsg`, `titleAttempts`. Moving them into a new object would mean rewriting the
+// 74 references inside runAgent plus every reader in composeFrame and the panels, for no gain:
+// the fields would live one property deeper and every line that touches them would change.
+//
+// So the core HOLDS the state rather than replacing it. A headless run creates its own state
+// object and hands it to a core; the TUI hands over the one it already builds. Same code, one
+// carrier, no churn.
+//
+// WHAT THE CORE ADDS
+// ------------------
+// Three things the state object cannot do for itself, and which a second front end needs:
+//
+//   * `submit(text)` — start a turn, from anywhere
+//   * `dispatch(cmd, arg)` — run a slash command, from anywhere
+//   * a lifecycle — `onEvent` out, `interrupt` in, without a terminal to route through
+//
+// Those are exactly the 207 lines of hub actions plus the 100 of submit, which is why they are
+// what gets extracted rather than the 1020 of runAgent.
+import { HEADLESS_VIEW } from './session-view.js';
+
+// The team the LEAD is on.
+//
+// A lead has no async identity — only teammates do — so without this every tool and command it
+// calls would have to be handed the team name, and the model does not know to pass it. One
+// process, one lead, one team: createTeam refuses a second.
+//
+// This is the ONLY copy. tools/team.js reads through here rather than keeping its own, or a
+// team created from the keyboard would be invisible to the model.
+let leadTeamName = null;
+
+/** The team the lead is leading, or null. */
+export function leadTeam() {
+  return leadTeamName;
+}
+
+/** Record it. Called when a team is created, from either the tool or the command. */
+export function setLeadTeam(name) {
+  leadTeamName = name || null;
+  return leadTeamName;
+}
+
+/** Forget it. Called when the team is dissolved. */
+export function clearLeadTeam() {
+  leadTeamName = null;
+}
+
+export class SessionCore {
+  /**
+   * @param {object} deps
+   * @param {object} deps.state   the live state object (the TUI's, or one built for a headless run)
+   * @param {object} deps.cfg
+   * @param {object} deps.session the persisted session record
+   * @param {object} [deps.view]  display adapter; HEADLESS_VIEW when there is no terminal
+   */
+  constructor({ state, cfg, session, view = HEADLESS_VIEW, host = null }) {
+    // The session machinery. Optional so a test can build a core without one, but a real
+    // session passes it: it holds the ONE stream buffer and the transcript recorder.
+    this.host = host;
+    this.state = state;
+    this.cfg = cfg;
+    this.session = session;
+    this.view = view;
+
+    /** Host callbacks the core does not own: run a turn, run a command, stop. */
+    this._runAgent = null;
+    this._dispatch = null;
+    this._quit = null;
+    /**
+     * The object `dispatch` destructures its UI callbacks from.
+     *
+     * NOT `this.view`: the view is the seam a SESSION sees (note/err/render/pick/form), while a
+     * command is written against the host's own names — `notice`, `openPicker`, `openForm`,
+     * `sendPrompt`, `saveSession`, `quit`. Passing the view left every panel-opening command
+     * (`/help`, `/model`, `/exit`) throwing `openPicker is not a function`.
+     */
+    this._commandHost = null;
+    /** Subscribers, for a front end that wants the turn's events as they happen. */
+    this._listeners = new Set();
+  }
+
+  /**
+   * Hand the core the functions only the embedding process can provide.
+   *
+   * `runAgent` stays where it is for now: it is 1020 lines woven through the TUI's paint path,
+   * and moving it in one piece is the step that cannot be verified halfway. Wiring it here means
+   * the core's interface is complete and a later step can move the implementation without any
+   * caller changing.
+   */
+  bind({ runAgent, dispatch, quit, commandHost }) {
+    if (runAgent) this._runAgent = runAgent;
+    if (dispatch) this._dispatch = dispatch;
+    if (quit) this._quit = quit;
+    if (commandHost) this._commandHost = commandHost;
+    return this;
+  }
+
+  /** Subscribe to turn events. Returns an unsubscribe. */
+  onEvent(fn) {
+    this._listeners.add(fn);
+    return () => this._listeners.delete(fn);
+  }
+
+  emit(event) {
+    for (const fn of this._listeners) {
+      try { fn(event); } catch { /* a listener must not break the turn */ }
+    }
+  }
+
+  // ---- the actions a front end may take ------------------------------------
+
+  /**
+   * Start a turn with `text`.
+   *
+   * Rejects rather than returning an error code: the caller is an HTTP handler or a key press,
+   * and both need a throw to answer with a status or a message. `hub.call` already converts that
+   * shape, so the two agree.
+   */
+  async submit(text) {
+    if (typeof text !== 'string' || !text.trim()) throw new Error('empty message');
+    if (!this._runAgent) throw new Error('this session has no agent runner');
+    return this._runAgent(text, {}, this.view);
+  }
+
+  /** Run a slash command. `cmd` may be `/name args` or just `name`. */
+  async dispatch(cmd, arg) {
+    if (!this._dispatch) throw new Error('this session has no command dispatcher');
+    const raw = String(cmd || '').trim();
+    if (!raw) throw new Error('empty command');
+    const sp = raw.indexOf(' ');
+    const name = sp === -1 ? raw : raw.slice(0, sp);
+    const rest = sp === -1 ? String(arg || '') : raw.slice(sp + 1).trim();
+    const out = await this._dispatch(name, rest, this.state, this.cfg, this.session, this._commandHost);
+    if (this.state._quit && this._quit) this._quit();
+    return out;
+  }
+
+  /**
+   * Stop the running turn.
+   *
+   * Throws when nothing is running rather than doing nothing: a front end that reports "stopped"
+   * for a turn that had already finished is lying to the user about what happened.
+   */
+  async interrupt() {
+    const agent = this.state.agent;
+    if (!agent || typeof agent.interrupt !== 'function') throw new Error('nothing is running');
+    agent.interrupt();
+  }
+
+  /** Whether a turn is in flight. */
+  get running() {
+    return !!this.state.running;
+  }
+
+  /**
+   * The queued prompts, as a plain array.
+   *
+   * A copy: the queue is drained by the turn loop, and a front end iterating the live array would
+   * see it shift under it.
+   */
+  get queued() {
+    return [...(this.state.queued || [])];
+  }
+
+  /** Queue a prompt for after the current turn. */
+  enqueue(text) {
+    const t = String(text || '').trim();
+    if (!t) return false;
+    (this.state.queued = this.state.queued || []).push(t);
+    this.view.pubStatusField('queued', this.queued);
+    return true;
+  }
+
+  /** Drop every queued prompt. */
+  clearQueue() {
+    this.state.queued = [];
+    this.view.pubStatusField('queued', []);
+  }
+
+  /**
+   * Change the permission mode.
+   *
+   * Validated here rather than by the caller: `ask` / `yolo` / `auto` is the whole set the rest
+   * of the program understands, and a typo reaching `state.mode` would be read as a mode that
+   * denies everything.
+   */
+  async setMode(mode) {
+    const m = String(mode || '');
+    if (!['ask', 'yolo', 'auto'].includes(m)) throw new Error(`unknown mode: ${m}`);
+    this.state.mode = m;
+    if (this.session) this.session.mode = m;
+    return m;
+  }
+
+  /** The permission mode in force. */
+  get mode() {
+    return this.state.mode || 'ask';
+  }
+}

package/src/session-host.js

@@ -0,0 +1,213 @@
+// The pieces a running session needs that are not the display.
+//
+// WHY A HOST RATHER THAN A BIGGER CORE
+// ------------------------------------
+// After the display calls were routed through the view, an audit of runAgent's 1024 lines found 25
+// remaining TUI dependencies across 14 names. Only FOUR of those genuinely need a foreground
+// process (`state.scroll`, `dropScrollPin`, `beginTurn`, `refreshGitInfo`) — and three of the four
+// are harmless no-ops headless. The other seven names are session machinery that happened to be
+// written inside startTUI's closure:
+//
+//   flushStream            drains the stream buffer
+//   recordTranscriptRow    appends to the persisted display history
+//   normalizeMsg           its shape is what every renderer and the web UI read
+//   generateTitle          names the session
+//   stopTask               stops a background job
+//   runShellCommand        the `!cmd` path
+//
+// Those belong to a session, not to a terminal. The host is where they live so both a TUI and a
+// daemon can have them.
+import {
+  StreamBuffer, StreamOp,
+} from './stream-buffer.js';
+
+/**
+ * The parts of a session that outlive any one turn.
+ *
+ * `view` decides where anything the user should see goes; everything else here is state the
+ * session carries. Constructed by the TUI with its own painters, and by the daemon with
+ * HEADLESS_VIEW.
+ */
+export class SessionHost {
+  constructor({ state, cfg, session, view, onEvent } = {}) {
+    this.state = state;
+    this.cfg = cfg;
+    this.session = session;
+    this.view = view;
+    this.onEvent = typeof onEvent === 'function' ? onEvent : () => {};
+
+    // One buffer for the whole session rather than one per turn: the pacing it does is about the
+    // pipe, not about the turn, and a fresh buffer per turn would drop whatever the previous one
+    // had not yet released.
+    this.streamBuf = new StreamBuffer();
+    this._recorder = null;
+
+    // Where revealed text goes. Three callbacks rather than an event, because this is not a
+    // notification — it is the append itself, and a host that only announced the text would
+    // lose every character the buffer released.
+    this.appenders = {
+      assistant: () => {},
+      reasoning: () => {},
+      settleReasoning: () => {},
+    };
+  }
+
+  /**
+   * Where `recordTranscriptRow` writes.
+   *
+   * Injected rather than imported: the recorder lives in session.js and reaches the disk, and a
+   * test (or a daemon with no store) must be able to run a session without one.
+   */
+  setRecorder(fn) {
+    this._recorder = typeof fn === 'function' ? fn : null;
+    return this;
+  }
+
+  /** Drain whatever the stream buffer is holding. Idempotent. */
+  flushStream() {
+    const ops = this.streamBuf.flush();
+    return this.applyStreamOps(ops);
+  }
+
+  /**
+   * Apply the ops the buffer hands back.
+   *
+   * The push methods RETURN the characters due right now and have already dequeued them, so
+   * dropping the return value loses that text permanently — this is the one rule the whole
+   * streaming path depends on, and it is why every push goes through here.
+   */
+  applyStreamOps(ops) {
+    if (!ops || !ops.length) return false;
+    const a = this.appenders;
+    for (const o of ops) {
+      // Text and reasoning go to DIFFERENT appenders — that is what keeps a reasoning block
+      // from overtaking the answer that followed it, and what closes the block at exactly the
+      // point the provider closed it.
+      if (o.op === StreamOp.Text) a.assistant(o.text);
+      else if (o.op === StreamOp.Reasoning) a.reasoning(o.text);
+      else if (o.op === StreamOp.CloseReasoning) a.settleReasoning();
+    }
+    return true;
+  }
+
+  /**
+   * Append a row to the persisted DISPLAY history.
+   *
+   * Separate from the chat log: `session.messages` is what gets sent to the model, while this is
+   * what the user saw — notices, warnings, plan cards, reasoning. `/save-history off` drops it,
+   * and a session without a recorder simply does not keep it.
+   */
+  recordTranscriptRow(msg) {
+    if (!this.session) return;
+    if (this.state.saveHistory === false) return;
+    if (!this._recorder) return;
+    try { this._recorder(this.session, msg, this.state); } catch { /* history is not worth a turn */ }
+  }
+
+  /**
+   * The canonical shape of a message.
+   *
+   * Every renderer reads rows shaped like this, and the web UI mirrors the same shape — so it is
+   * normalised once, here, rather than at each reader.
+   *
+   * `failed` is deliberately preserved: a failed tool result must render red, and dropping it made
+   * every failure look like ordinary output.
+   */
+  normalizeMsg(m) {
+    const msg = { ...(m || {}) };
+    if (msg.text == null && msg.content != null) msg.text = String(msg.content);
+    if (msg.content == null && msg.text != null) msg.content = msg.text;
+    if (msg.role === 'tool' && msg.failed === undefined && typeof msg.text === 'string') {
+      msg.failed = /^Error\b|^Cannot read\b|^Edit rejected/.test(msg.text);
+    }
+    return msg;
+  }
+
+  /**
+   * Close the pending reasoning row.
+   *
+   * A reasoning block stays `pending` while it streams and is what the renderer draws a live
+   * cursor on. Nothing in a headless run draws it, but the flag is what the transcript records
+   * — a block left pending would be read back as still running on the next resume.
+   */
+  settleThinking() {
+    const t = [...(this.state.chat || [])].reverse().find((m) => m.role === 'thinking' && m.pending);
+    if (t) t.pending = false;
+  }
+
+  /**
+   * Add `n` to the turn's output-token estimate.
+   *
+   * Called for EVERY stream the model produces — answer, reasoning, tool arguments — because
+   * the turn is billed for all three. The provider's exact figure replaces the estimate when the
+   * `usage` event lands, so this only has to be roughly right while it is on screen.
+   *
+   * `n` may be FRACTIONAL. Streaming callers pass `estimateTokensFloat` so that a chunk smaller
+   * than four characters contributes its real share instead of a whole rounded token — see that
+   * function for why summing rounded chunks inflated the figure by a third. Only the DISPLAYED
+   * total is rounded.
+   */
+  countOutputTokens(n) {
+    const add = Number(n) || 0;
+    if (add <= 0) return;
+    const st = this.state;
+    st.turnOutputEstimate = (st.turnOutputEstimate || 0) + add;
+    // SETTLED + ESTIMATE, not the estimate alone: a turn makes one request per step, and
+    // `usage` closes each one. Showing only the live estimate made the counter restart from
+    // zero at the start of every step.
+    st.turnOutputTokens = Math.round((st.turnOutputSettled || 0) + st.turnOutputEstimate);
+  }
+
+  /** Whether tools may touch paths outside the workspace. Read live off config. */
+  externalAllowed() {
+    return !!(this.cfg && this.cfg.allowExternal);
+  }
+
+  /**
+   * Write the session's live switches back to the record.
+   *
+   * Mode, plan, focus and swarm are all things a command flips mid-session and all of which a
+   * resume has to bring back. Saved here rather than at turn end so `/mode yolo` followed by a
+   * crash does not come back as `ask`.
+   */
+  persistState() {
+    const s = this.session;
+    if (!s) return;
+    const st = this.state;
+    s.mode = st.mode;
+    s.plan = !!st.plan;
+    s.planPath = st.planPath || null;
+    s.focus = !!st.focus;
+    s.swarm = !!st.swarm;
+    s.todos = st.todos || [];
+    return s;
+  }
+
+  /**
+   * Name the session from its first exchange.
+   *
+   * Returns the title, or '' when there is nothing to name it with. A failure returns '' rather
+   * than throwing: an unnamed session is a cosmetic loss, and the caller has a turn in flight.
+   */
+  async generateTitle(userText, { makeTitle } = {}) {
+    if (!this.session) return '';
+    if (this.session.title) return this.session.title;
+    if (typeof makeTitle !== 'function') return '';
+    const asked = String(userText || '').replace(/\s+/g, ' ').trim().slice(0, 400);
+    if (!asked) return '';
+    try {
+      const title = await makeTitle(asked, this.cfg);
+      if (title && !this.session.title) {
+        this.session.title = String(title).slice(0, 80);
+        this.view.syncChat && this.view.syncChat(this.state.chat || []);
+      }
+      return this.session.title || '';
+    } catch {
+      // The caller counts attempts; a throw here would end a turn over a label.
+      return '';
+    }
+  }
+}
+
+/** The op kinds the buffer emits, re-exported so a consumer does not import two modules. */
+export const HOST_STREAM_OPS = StreamOp;

package/src/session-view.js

@@ -0,0 +1,110 @@
+// The seam between a session and the thing displaying it.
+//
+// WHY THIS EXISTS
+// ---------------
+// `runAgent` is 1020 lines and mixes three concerns: assembling the request, driving the agent
+// loop, and PAINTING. The painting is what tied a session to the TUI — a session could only run
+// in the process that drew it, so the web UI had to proxy to a live terminal and a session whose
+// terminal had closed could never be continued.
+//
+// The audit that motivated this file counted the damage: of 1020 lines, only 127 places touch the
+// TUI at all, and just 27 of those are rendering calls and 5 are modals. Everything else is
+// session state the session would carry anyway. So the seam is real and small enough to cut.
+//
+// WHY A PARAMETER RATHER THAN A GLOBAL
+// ------------------------------------
+// The TUI passes its own painters; a headless run passes no-ops. A module-level "current view"
+// would make two sessions in one process share whatever was set last — the same failure the
+// teammate identity had, and the reason that one uses AsyncLocalStorage.
+//
+// Every method is optional at the call site via `view?.x?.()`. A view that only wants rows should
+// not have to implement file dialogs, and a headless run must not have to stub twenty methods to
+// run one turn.
+
+/** A view that draws nothing. Used by headless runs and by tests. */
+export const HEADLESS_VIEW = {
+  note: () => {},
+  err: () => {},
+  render: () => {},
+  renderSoon: () => {},
+  // The transcript. A headless run still APPENDS to it: the chat log is what gets persisted
+  // and what the web UI streams, so dropping this would lose the turn rather than merely not
+  // drawing it.
+  addChat: () => {},
+  sync: () => {},
+  pushRow: () => {},
+  patchRow: () => {},
+  syncChat: () => {},
+  pubStatusField: () => {},
+  edit: async () => null,
+  pick: async () => null,
+  form: async () => null,
+};
+
+/**
+ * Wrap a real TUI's painters into the shape `runAgent` expects.
+ *
+ * `deps` is what `startTUI` already owns: the hub, the frame painter, the chat log. Passing them
+ * in rather than importing them keeps this module free of the 17k-line file it would otherwise
+ * have to import — and makes the seam testable without a terminal.
+ */
+export function tuiView(deps) {
+  const {
+    // `hub` is NOT destructured: it is assigned long after this runs, so reading it here
+    // would freeze the null that exists now and every web push would silently no-op. Read it
+    // through `deps.hub` at the call site. The rest are plain functions that never change.
+    renderFrame, renderSoon, addChat, notice, syncWeb,
+    openEditor, openPicker, openForm, stdout,
+  } = deps;
+
+  return {
+    // A line the USER should read. In the TUI these are the transient notices; a teammate's
+    // failure that is only logged is a failure nobody sees.
+    note: (text, kind = 'info') => { try { notice(text, kind); } catch { /* the UI itself */ } },
+
+    // The same notice at ERROR level. Separate method because the TUI's `appErr(m)` is
+    // `notice(m, 'error')` — the level is not in the call, so a plain rename to `note` would
+    // quietly downgrade every failure to an ordinary message.
+    err: (text) => { try { notice(text, 'error'); } catch { /* the UI itself */ } },
+
+    // Repaint now, and soon. Two names because the call sites differ in intent: one has just
+    // changed what should be on screen, the other is mid-stream and wants to coalesce.
+    render: () => { try { renderFrame(); } catch { /* a paint failure must not kill a turn */ } },
+    renderSoon: () => { try { (renderSoon || renderFrame)(); } catch { /* as above */ } },
+
+    // Append to the transcript. This is DATA, not drawing: the chat log is what `--continue`
+    // saves and what the web UI streams, so it has to work with no terminal at all.
+    addChat: (msg) => { try { addChat(msg); } catch { /* as above */ } },
+
+    // A row that is updated in place rather than appended — a running tool call, a compaction
+    // block. Optional: a view without the notion of "the same row" simply ignores it.
+    pushRow: (row) => { try { deps.hub && deps.hub.pushRow(row); } catch { /* best effort */ } },
+    patchRow: (id, patch) => { try { deps.hub && deps.hub.patchRow(id, patch); } catch { /* best effort */ } },
+
+    // The transcript, mirrored for a watching browser. Best effort by design — the web UI
+    // lagging is not a reason to fail a turn.
+    syncChat: (chat) => { try { deps.hub && deps.hub.syncChat(chat); } catch { /* best effort */ } },
+    sync: () => { try { syncWeb && syncWeb(); } catch { /* best effort */ } },
+    pubStatusField: (field, value) => {
+      try { deps.hub && deps.hub.pubStatusField(field, value); } catch { /* best effort */ }
+    },
+
+    // The two things a headless run genuinely cannot do. Returning null rather than throwing
+    // lets the caller fall back to a textual answer, which is what the web UI wants anyway.
+    edit: (spec) => { openEditor && openEditor(spec); return null; },
+    pick: (spec) => { openPicker && openPicker(spec); return null; },
+    form: (spec) => { openForm && openForm(spec); return null; },
+
+    // Terminal geometry, for the parts of a transcript that wrap. A headless run has no width to
+    // wrap to, so it reports a conventional one rather than failing.
+    dims: () => {
+      try {
+        const [cols, rows] = stdout.getWindowSize();
+        return { cols: cols || 80, rows: rows || 24 };
+      } catch { return { cols: 80, rows: 24 }; }
+    },
+
+    /** True when this view can show a modal. Callers that need one must check. */
+    interactive: true,
+  };
+}

package/src/settings-schema.js

@@ -278,15 +278,18 @@ export function displayValue(cfg, key) {
   if (!def) return '';
   const v = effectiveValue(cfg, key);
   if (def.kind === 'bool') return v === 'true' ? 'on' : 'off';
-  if (def.kind === 'text') {
-    if (!v) return '(unset)';
-    const first = v.split('\n')[0];
-    return v.includes('\n') || first.length > 40 ? `${first.slice(0, 40)}…` : first;
-  }
-  // An empty value reads as `(unset)` for EVERY kind, not only `string`. `protocol` is an
-  // enum whose default is the empty string, so its row rendered with a blank value column —
-  // indistinguishable from a row whose value failed to render.
-  if (!v) return '(unset)';
+  // `text` is returned WHOLE. It used to be cut to forty characters here, which made the
+  // value useless to a caller that needed to measure or edit it. Abbreviating is the
+  // renderer's job — see `proseSummary`.
+  //
+  // An empty value reads as `(unset)` for EVERY kind, not only `string`: `protocol` is an
+  // enum whose default is the empty string, so its row rendered with a blank value column.
+  //
+  // Whitespace alone is unset too. `!v` only catches the empty string, so '   ' rendered as a
+  // blank cell — the same as a value that failed to render. Tested on the trimmed copy and the
+  // value returned RAW: a trailing newline is part of a prompt, and trimming the value itself
+  // would corrupt it.
+  if (!v || !String(v).trim()) return '(unset)';
   return v;
 }