@hncode/hncode 0.5.0 → 0.5.2

package/bin/install.cjs

@@ -30,35 +30,27 @@ for (const dir of dirs) {
 
 // Check if config file exists
 if (!fs.existsSync(configFile)) {
-  const defaultConfig = `# hncode Configuration
-# Generated by hncode install script
+  const defaultConfig = `# hncode configuration
+#
+# Nothing here is required: every value has a default, and the same keys can be set with
+# HNCODE_* environment variables or from /settings once hncode is running.
+#
+# Model and provider are deliberately left out. Naming one here starts hncode on a model
+# you may have no key for, and the first turn fails against that provider instead of
+# asking you to choose. Set up a provider with /provider, then pick a model with /model.
 
-# Default model (change this to your preferred model)
-default_model = "gpt-4o-mini"
-
-# Optional: Add providers directly here
-# Uncomment and configure as needed:
-# 
 # [providers.openai]
 # base_url = "https://api.openai.com/v1"
-# api_key = "your-api-key-here"
+# api_key  = "sk-..."       # or set HNCODE_API_KEY
 # protocol = "openai"
-
-# Or use environment variables:
-# HNCODE_API_KEY="your-key"
-# HNCODE_PROVIDER="openai"
-# HNCODE_MODEL="gpt-4o-mini"
-
 `;
 
   fs.writeFileSync(configFile, defaultConfig);
   console.log(`\n✅ Created default configuration at: ${configFile}`);
   console.log('\n💡 Next steps:');
-  console.log('   1. Edit ~/.hncode/config.toml with your API key');
-  console.log('   2. Or set environment variables:');
-  console.log('      export HNCODE_API_KEY="your-key"');
-  console.log('      export HNCODE_PROVIDER="openai"');
-  console.log('   3. Run "hncode" to start!');
+  console.log('   1. Start hncode and run /provider to add an API key');
+  console.log('   2. Then /model to pick one');
+  console.log('   Both write to the config above, so there is nothing to edit by hand.');
 } else {
   console.log(`\nℹ️  Configuration already exists at: ${configFile}`);
   console.log('   Run "hncode init" to regenerate or edit manually.');
@@ -66,30 +58,18 @@ default_model = "gpt-4o-mini"
 
 console.log('\n✨ hncode is ready to use!');
 
-// Try to refresh environment automatically
-try {
-  const platform = os.platform();
-  
-  if (platform === 'win32') {
-    // Windows: Use PowerShell to refresh environment
-    const { execSync } = require('child_process');
-    try {
-      execSync('$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User");', { stdio: 'pipe' });
-      console.log('✓ Environment refreshed automatically (PowerShell)');
-    } catch (e) {
-      console.log('ℹ️  To refresh environment in PowerShell:');
-      console.log('   . "$env:LOCALAPPDATA\\npm\\npm.cmd"');
-      console.log('   Or simply close and reopen your terminal');
-    }
-  } else {
-    // Unix-like systems
-    console.log('ℹ️  Please run one of these to refresh environment:');
-    console.log('   source ~/.zshrc    # For Zsh');
-    console.log('   source ~/.bashrc   # For Bash');
-    console.log('   Or simply close and reopen your terminal');
-  }
-} catch (err) {
-  console.log('ℹ️  Note: You may need to restart your terminal');
+// Tell the user how to pick up the new command.
+//
+// This used to run PowerShell to prepend the npm global path, and print "Environment
+// refreshed automatically". That cannot work: `execSync` starts a CHILD shell, so the
+// `$env:Path` it sets dies with that process. The claim is gone; the note below is true.
+if (os.platform() === 'win32') {
+  console.log('ℹ️  If "hncode" is not found, open a new terminal (the PATH is updated at');
+  console.log('   login), or run this in the current one:');
+  console.log('     $env:Path = [System.Environment]::GetEnvironmentVariable("Path","User") + ";" + $env:Path');
+} else {
+  console.log('ℹ️  If "hncode" is not found, open a new terminal, or re-read your shell');
+  console.log('   configuration:  source ~/.zshrc   (or ~/.bashrc)');
 }
 
 console.log('');

package/bin/preinstall.cjs

@@ -25,18 +25,4 @@ if (major < 20) {
 const platform = os.platform();
 console.log(`✓ Platform: ${platform}`);
 
-// Check if already installed globally
-try {
-  const { execSync } = require('child_process');
-  const npm = execSync('npm list -g hncode 2>&1').toString();
-  if (npm.includes('hncode')) {
-    console.log('ℹ️  hncode is already installed globally');
-    console.log('   Run "npm uninstall -g hncode" to reinstall.\n');
-  } else {
-    console.log('✓ Not installed globally yet\n');
-  }
-} catch (e) {
-  console.log('✓ Not installed globally yet\n');
-}
-
 console.log('✅ Environment check passed!\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hncode/hncode",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "hncode — A cyan-blue TUI AI coding agent with zero runtime dependencies.",
   "type": "module",
   "main": "src/index.js",

package/src/agent-task.js

@@ -76,7 +76,10 @@ function store(ctx) {
  */
 export function createTask(ctx, kind, options = {}) {
   const tasks = store(ctx);
-  const prefix = kind === 'process' ? 'bash' : kind === 'agent' ? 'agent' : 'question';
+  // A teammate is its own kind rather than falling through to 'question': the id prefix is
+  // what a reader of a task list uses to tell at a glance what kind of work it is.
+  const PREFIX = { process: 'bash', agent: 'agent', teammate: 'mate' };
+  const prefix = PREFIX[kind] || 'question';
   const task = {
     taskId: newTaskId(prefix),
     kind,
@@ -101,10 +104,18 @@ export function createTask(ctx, kind, options = {}) {
     task.subagentType = options.subagentType;
     task.model = options.model;
     task.thinkingEffort = options.thinkingEffort;
+  } else if (kind === 'teammate') {
+    task.teamName = options.teamName;
+    task.memberName = options.memberName;
+    task.agentId = options.agentId;
   } else if (kind === 'question') {
     task.questionCount = options.questionCount || 0;
     task.toolCallId = options.toolCallId;
   }
+  // WHICH TASK THIS ONE BELONGS TO. A swarm's subagents are tasks of their own so /tasks can show
+  // what each is doing, and this is what groups them under the swarm that launched them. Absent
+  // for a top-level task, which is the common case.
+  if (options.parentTaskId) task.parentTaskId = String(options.parentTaskId);
   // Every task exposes its buffered output through `output`. The chunks are
   // stored raw and decoded lazily:
   //   * a process appends Buffer chunks -> decode as UTF-8

package/src/agent.js

@@ -3,7 +3,7 @@
 // model answers without tool calls (or a step/interrupt condition is hit).
 
 import { LLM, setToolsList } from './llm.js';
-import { tools, getTool, llmTools } from './tools/index.js';
+import { tools, combinedTools, getTool, llmTools } from './tools/index.js';
 import { DELEGATION_TOOLS } from './subagent-types.js';
 import { estimateMessagesTokens, estimateRequestOverhead, estimateTokens, messageTokens, TokenLedger, forgetMessageTokens } from './term.js';
 import { runHooks, runPatch, runPatchSync } from './plugin.js';
@@ -140,9 +140,10 @@ function hashKey(s) {
     h = (h * 0x01000193) >>> 0;
   }
   return h.toString(36) + '-' + str.length.toString(36);
-  return h.toString(36) + '-' + str.length.toString(36);
 }
 
+// Render what an Edit actually changed, for the MODEL's tool result.
+
 // Render what an Edit actually changed, for the MODEL's tool result.
 //
 // The UI has always received the edit through `editDiff` (see the tool_result
@@ -166,10 +167,18 @@ export function formatEditDiffForModel(diff, maxLines = 400) {
   const out = [];
   out.push('');
   out.push('--- diff ---');
+  // Unchanged lines above and below, unmarked, so the change can be LOCATED. Without them this
+  // was a quoted block with no indication of where in the file it landed — and identical-looking
+  // code appears in many places, so neither the model nor the user could confirm the edit hit
+  // the intended one rather than a same-text block further down.
+  const before = (diff.context && Array.isArray(diff.context.before)) ? diff.context.before : [];
+  const after = (diff.context && Array.isArray(diff.context.after)) ? diff.context.after : [];
+  for (const c of before) out.push('  ' + String(c.n).padStart(4) + '   ' + c.text);
   let n = startLine;
   for (const l of oldLines) out.push('  ' + String(n++).padStart(4) + ' - ' + l);
   n = startLine;
   for (const l of newLines) out.push('  ' + String(n++).padStart(4) + ' + ' + l);
+  for (const c of after) out.push('  ' + String(c.n).padStart(4) + '   ' + c.text);
   // A whole-file edit (a Write-sized `new`) must not be echoed back in full.
   if (out.length > maxLines + 3) {
     const hidden = out.length - (maxLines + 3);
@@ -205,6 +214,37 @@ function toolResultLimitsEnabled() {
   return !/^(0|off|false|no)$/i.test(String(process.env.HNCODE_TOOL_RESULT_LIMITS || ''));
 }
 
+/**
+ * A tool's return value, as the STRING the model can be sent.
+ *
+ * Every tool in `src/tools/` returns a plain string except the team tools, which return
+ * `{ content }` / `{ error }`. That object went into the `tool` message verbatim, and a provider
+ * that expects a string rejects the NEXT request with `missing type field in content item at
+ * index 0` — so a teammate's first `SendMessage` worked and then the conversation died, one
+ * message in. The symptom was a team that says hello and then never answers again.
+ *
+ * Returns `null` for the one shape that must stay an OBJECT: `ReadMediaFile` returns
+ * `{ text, media: [...] }`, and the media parts travel as structured blocks the caller builds
+ * from the object. Stringifying that would attach no image at all, so the caller keeps it.
+ *
+ * Normalised here, at the single point every tool result passes through, rather than in the
+ * team tools: a second tool family making the same choice cannot reintroduce the bug.
+ */
+function toolResultText(value) {
+  if (typeof value === 'string') return value;
+  if (value == null) return '';
+  if (typeof value === 'object') {
+    // Leave a media result alone — the caller needs the parts, not a sentence about them.
+    if (Array.isArray(value.media)) return null;
+    if (typeof value.content === 'string') return value.content;
+    if (typeof value.error === 'string') return value.error;
+    if (typeof value.text === 'string') return value.text;
+    try { return JSON.stringify(value); } catch { return String(value); }
+  }
+  return String(value);
+}
+
+
 
 export const SYSTEM_PROMPT = `You are hncode, a coding agent in the user's terminal on ${process.platform}.
 You work inside a workspace directory using the tools provided.
@@ -280,9 +320,9 @@ export class Agent {
     // even if the filter would have allowed them. The catalog already excludes
     // them from every profile; this is the hard backstop that also covers the
     // `null` (= everything) case, so a subagent can never spawn another agent.
-    const filtered = (Array.isArray(cfg.toolFilter) && cfg.toolFilter.length
-      ? tools.filter((t) => cfg.toolFilter.includes(t.name))
-      : tools
+const filtered = (Array.isArray(cfg.toolFilter) && cfg.toolFilter.length
+      ? combinedTools().filter((t) => cfg.toolFilter.includes(t.name))
+      : combinedTools()
     )
       .filter((t) => !(cfg.noDelegation && DELEGATION_TOOLS.includes(t.name)))
       // AgentSwarm is gated behind swarm mode, like Agent is gated behind the user
@@ -420,9 +460,10 @@ export class Agent {
     const used = this.usedTokens();
     const maxSize = Math.max(1, Math.floor((used || (maxCtx || 512000) * 0.85) * keepRatio));
     const msgs = this.messages || [];
-    // Never cut inside the LEADING system block. `msgs[0]` is the assembled system
-    // prompt, and canSplitAfter() would happily allow a split right after it — which
-    // would drop the prompt itself and leave the request with no instructions.
+    // How far the LEADING system block runs. A cut before `floor` would land inside it,
+    // splitting the assembled system prompt across the drop boundary. The block itself is
+    // carried over by the trim (renamed `leadingSystem` there), because a cut can only
+    // ever land at or after its end.
     let floor = 0;
     while (floor < msgs.length && msgs[floor] && msgs[floor].role === 'system') floor++;
     let recent = 1;
@@ -435,13 +476,66 @@ export class Agent {
       // call. It is also the memoised form, so repeating this walk after a large tool
       // result is a WeakMap hit rather than a re-measure.
       size += messageTokens(msgs[split], null);
-      if (split > floor && canSplitAfter(msgs, split - 1)) bestSplit = split;
+      // The guard the leading system block needs, and the reverse of the `split > floor`
+      // this used to test. A cut at `split` drops `[0..split-1]`, so `split >= floor`
+      // keeps the cut at or after the block's end and never inside it — which is what
+      // the block's comment above asks for, and what `split > floor` inverted.
+      if (split >= floor && canSplitAfter(msgs, split - 1)) bestSplit = split;
       if (size >= maxSize && bestSplit !== undefined) break;
     }
     return bestSplit ?? 0;
   }
 
+  /**
+   * Trim the history at a legal cut and append the summary + continuation note.
+   *
+   * Extracted from `run()` so it can be tested against the REAL implementation. A test that
+   * re-implemented these four lines was green against a duplicated system prompt — the copy
+   * carried its own guard, which is the failure mode of testing a restatement.
+   *
+   * Returns `{ split, dropped }`.
+   *
+   * Shape: `[ ...lead, ...kept, summary, continuation ]`.
+   *
+   * The summary is a USER message wrapped in a `<system-reminder>` (kimi's shape), not a
+   * `system` one. Two reasons:
+   *   * the TUI rebuilds the system prompt from scratch each turn and SKIPS every `system`
+   *     entry in the stored history, so a system summary was dropped before the model saw it;
+   *   * the turn-end save filters `system` out of the session, so it was not persisted either
+   *     — history trimmed AND summary lost at both ends, which made "compaction" pure data loss.
+   * The continuation note goes LAST so the model's next move is "keep going" rather than
+   * "answer the summary".
+   */
+  applyCompactionSplit(maxCtx, summary) {
+    const split = this.computeCompactSplit(maxCtx);
+    const keep = this.messages.slice(split);
+    const dropped = this.messages.length - keep.length;
+    // The LEADING system block is carried over explicitly. It sits at the head of the array
+    // and the cut drops everything before `split`, so it would otherwise be taken by every
+    // compaction — leaving the request with no instructions, which is the loss the `floor`
+    // guard in computeCompactSplit exists to prevent.
+    let leadingSystem = 0;
+    while (leadingSystem < this.messages.length
+      && this.messages[leadingSystem] && this.messages[leadingSystem].role === 'system') leadingSystem++;
+    // Only what the cut actually REMOVED. `keep` is `slice(split)`, so at `split === 0` it
+    // still contains the whole array including the block — prepending the block then sends the
+    // system prompt twice, and `llm.js` concatenates every system message into the request, so
+    // it would stay doubled in every compacted request from then on.
+    const lead = split > 0 ? this.messages.slice(0, leadingSystem) : [];
+    const summaryText = summary
+      ? `${COMPACTION_SUMMARY_PREFIX}\n${summary}`
+      : `${COMPACTION_SUMMARY_PREFIX}\n(no summary available)`;
+    this.messages = [
+      ...lead,
+      ...keep,
+      { role: 'user', _harness: true, content: wrapSystemReminder(summaryText) },
+      { role: 'user', _harness: true, content: wrapSystemReminder(COMPACTION_CONTINUATION_TEXT) },
+    ];
+    return { split, dropped };
+  }
+
   async run() {
+    // Clear any interrupt flag left from a previous (interrupted) turn. This runs at
     // Clear any interrupt flag left from a previous (interrupted) turn. This runs at
     // the start of EVERY turn, so a stalled Esc/Ctrl-C from an earlier compaction can
     // never suppress auto-compaction on the next message. (The constructor also
@@ -655,29 +749,7 @@ export class Agent {
           break;
         }
         // NOW trim, at a split point the boundary rule allows.
-        const split = this.computeCompactSplit(maxCtx);
-        const keep = this.messages.slice(split);
-        const droppedCount = this.messages.length - keep.length;
-        // Shape: [ ...kept, summary, continuation ].
-        //
-        // The summary is a USER message wrapped in a <system-reminder> (kimi's
-        // shape), not a `system` message. Two reasons:
-        //   * the TUI rebuilds the system prompt from scratch each turn and SKIPS
-        //     every `system` entry in the stored history, so a system summary was
-        //     dropped before the model ever saw it;
-        //   * the turn-end save filters `system` out of the session, so it was not
-        //     persisted either — history trimmed AND summary lost at both ends,
-        //     which made "compaction" pure data loss.
-        // The continuation note goes LAST so the model's next move is "keep going"
-        // rather than "answer the summary".
-        const summaryText = summary
-          ? `${COMPACTION_SUMMARY_PREFIX}\n${summary}`
-          : `${COMPACTION_SUMMARY_PREFIX}\n(no summary available)`;
-        this.messages = [
-          ...keep,
-          { role: 'user', _harness: true, content: wrapSystemReminder(summaryText) },
-          { role: 'user', _harness: true, content: wrapSystemReminder(COMPACTION_CONTINUATION_TEXT) },
-        ];
+        const { split, dropped: droppedCount } = this.applyCompactionSplit(maxCtx, summary);
         // The array was REPLACED, so every count the ledger held describes messages
         // that no longer exist. `sync` would notice on its own (the first/last
         // identities no longer match), but resetting here states the intent at the
@@ -702,8 +774,10 @@ export class Agent {
       // first, so it stays recoverable.
       //
       // Trigger: the request reached `trimThreshold` (50% by default) of the window.
-      // Target: keep `trimKeepRatio` (30% by default) of the tool-result TEXT,
-      // newest first. Skipped while a compaction just ran (that already shrank
+      // Target: keep `trimKeepRatio` (30% by default) of the tool-result TEXT, newest
+      // first. A different denominator from the trigger on purpose: the trigger asks
+      // about the window, this asks about the removable output. Skipped while a
+      // compaction just ran (that already shrank
       // things) and above the compaction trigger (compaction is the right tool by
       // then, and the two must not fight over the same history).
       const trimThreshold = Number.isFinite(this.cfg.trimThreshold) ? this.cfg.trimThreshold : DEFAULT_TRIM_THRESHOLD;
@@ -929,7 +1003,13 @@ export class Agent {
         let _args = tc.args; let _skip = false;
         try { const out = await runPatch('toolDispatch', { name: tc.name, args: tc.args, ctx: this.ctx }, (c) => c); if (out) { _args = out.args !== undefined ? out.args : tc.args; if (out.skip) _skip = true; } } catch (e) { console.error('[hncode-plugin] toolDispatch error:', e.message); }
         if (_skip) { result = '[skipped by plugin: ' + tc.name + ']'; ok = true; }
-        else result = await tool.execute(_args, this.ctx);
+        else {
+          const raw = await tool.execute(_args, this.ctx);
+          // `null` means the tool returned a structured MEDIA result: keep the object so the
+          // image blocks can be built from it. Only a plain value is stringified.
+          const text = toolResultText(raw);
+          result = text === null ? raw : text;
+        }
         } catch (err) {
           result = `Error running ${tc.name}: ${err.message}`;
           ok = false;

package/src/cell-buffer.js

@@ -126,6 +126,11 @@ export function renderCells(cells) {
     }
     out += c.ch;
   }
+  // Close the LAST run too. Without this the final style stayed open past the end of the
+  // row, and a caller that concatenates rows — `drawFrameBuffer` does, once per line —
+  // carried it into the next one: a card drawn over a dimmed or highlighted row tinted
+  // every line below it, and the row's own trailing SGR was simply lost.
+  if (cur !== null && cur !== '') out += RESET;
   return out;
 }
 

package/src/clipboard.js

@@ -57,16 +57,34 @@ const ONESHOT_MS = 20000;
 
 function win() { return process.platform === 'win32'; }
 
-// ---------------------------------------------------------------- copy
+/**
+ * Put text on the clipboard.
+ *
+ * WINDOWS: `Set-Clipboard` through PowerShell, NOT `clip.exe`.
+ *
+ * `clip.exe` takes UTF-16LE and needed a byte order mark to be read correctly — without it
+ * non-ASCII arrived as mojibake (`中文测试` came back as `-N噀Km諎`, measured). But the mark is then
+ * part of the clipboard text: every copy began with a zero-width U+FEFF that showed up as a stray
+ * invisible character wherever it was pasted. Measured over six samples, `Set-Clipboard` was better
+ * on every one:
+ *
+ *     copied           clip.exe + BOM             Set-Clipboard
+ *     hello            U+FEFF hello               hello
+ *     中文测试          U+FEFF 中文测试             中文测试
+ *     line1\nline2     U+FEFF line1 CRLF line2    line1\nline2   (line endings untouched)
+ *     emoji 🎉 ok       U+FEFF emoji 🎉 ok         emoji 🎉 ok
+ *
+ * It also needs no escaping: PowerShell receives a .NET string rather than a byte stream, so there
+ * is no console parser to satisfy — which is what the BOM and the quoting were working around.
+ *
+ * `clip.exe` stays as a fallback for a machine with no PowerShell at all, where a copy carrying a
+ * stray BOM beats no copy.
+ */
 export function copyText(text) {
   const s = String(text == null ? '' : text);
   if (!s) return false;
   if (win()) {
-    // clip.exe takes UTF-16LE. (`cmd /c echo "…" | clip` mangled quotes, '%'
-    // and newlines; plain UTF-8 input turned non-ASCII into mojibake.) Prefix the
-    // UTF-16 byte order mark (FF FE) so clip.exe is never left to guess the endian
-    // or treat input as ANSI — without it, non-ASCII on some Windows versions /
-    // code pages came out mojibake.
+    if (setClipboardText(s)) return true;
     cp.execSync('clip', { input: Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(s, 'utf16le')]), windowsHide: true, timeout: 5000 });
     return true;
   }
@@ -75,6 +93,24 @@ export function copyText(text) {
   return true;
 }
 
+/** `Set-Clipboard` via PowerShell. False when no PowerShell can be run. */
+function setClipboardText(s) {
+  // The text travels as base64 so nothing in it can end the script or be re-parsed. A quoted
+  // PowerShell literal would need every `'` doubled, and a newline or a backtick in the text would
+  // otherwise change what the script means.
+  const b64 = Buffer.from(s, 'utf16le').toString('base64');
+  const full = 'Add-Type -AssemblyName System.Windows.Forms; '
+    + '[System.Windows.Forms.Clipboard]::SetText('
+    + `[System.Text.Encoding]::Unicode.GetString([System.Convert]::FromBase64String('${b64}')))`;
+  for (const exe of [_psExe, 'powershell']) {
+    try {
+      cp.execFileSync(exe, ['-NoProfile', '-NonInteractive', '-Command', full], { timeout: 10000, windowsHide: true });
+      return true;
+    } catch { /* try the next exe */ }
+  }
+  return false;
+}
+
 // Which PowerShell the helper runs. `pwsh` (7) starts far faster than the built-in
 // `powershell` (5.1) — measured 1.9s vs 11.5s for the same image probe — and the image
 // path needs the WinForms/Drawing assemblies. This is only the PREFERRED name: it is