@hncode/hncode 0.2.0 → 0.3.1

package/README.md

@@ -67,6 +67,7 @@ hncode draws inspiration from several excellent projects:
 
 - **[Kimi Code](https://github.com/MoonshotAI/kimi-code)** - The original cyan-blue TUI coding agent that inspired this project's design and approach
 - **[Claude Code](https://github.com/anthropics/claude-code)** - The conversation flow and tool interaction patterns
+- **[Codex](https://github.com/openai/codex)** - Several behaviours were shaped by reading its open-source implementation: the AGENTS.md loading spec, the rule against spawning subagents unprompted, the plan-tool state machine, the review rubric, and parts of the system prompt
 
 Special thanks to the communities behind these projects for pushing the boundaries of AI-assisted coding.
 

package/README_CN.md

@@ -67,6 +67,7 @@ hncode 从以下几个优秀项目中汲取了灵感：
 
 - **[Kimi Code](https://github.com/MoonshotAI/kimi-code)** - 原始的青色蓝调终端界面 AI 编程助手，启发了本项目的设计和理念
 - **[Claude Code](https://github.com/anthropics/claude-code)** - 对话流程和工具交互模式
+- **[Codex](https://github.com/openai/codex)** - 通过阅读其开源实现，本项目确定了几处行为：AGENTS.md 的加载规则、未获明确许可不得开启子代理、计划工具的状态流转约束、代码审查的判定标准，以及系统提示词的部分内容
 
 特别感谢这些项目背后的社区，它们推动了 AI 辅助编程的边界。
 

package/package.json

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

package/src/agent-task.js

@@ -0,0 +1,178 @@
+// Background task registry — the single place tasks are created, listed, stopped
+// and read. Mirrors kimi-code's task model:
+//
+//   TaskInfo = base fields + a `kind`-discriminated payload
+//     kind 'process'  -> { command, pid, exitCode }        (Bash run_in_background)
+//     kind 'agent'    -> { agentId, subagentType, model, thinkingEffort }  (Agent)
+//     kind 'question' -> { questionCount, toolCallId }     (AskUserQuestion bg)
+//
+// Statuses match kimi exactly so the UI can share one vocabulary:
+//   running | completed | failed | timed_out | killed | lost
+//
+// Bash used to keep its own ad-hoc objects ('done'/'failed', `id`, `start`), which
+// is why the task panel could not show the same fields as kimi's. Everything now
+// goes through `createTask`, so a task always has the same shape no matter which
+// tool spawned it.
+
+export const TERMINAL_STATUSES = new Set(['completed', 'failed', 'timed_out', 'killed', 'lost']);
+
+export function isTerminal(status) {
+  return TERMINAL_STATUSES.has(status);
+}
+
+// `{prefix}-{8 chars}` like kimi's VALID_TASK_ID. Unique even for two tasks
+// created in the same millisecond (a bare Date.now() collided).
+let seq = 0;
+export function newTaskId(prefix = 'task') {
+  seq = (seq + 1) % 1e9;
+  const rand = Math.random().toString(36).slice(2, 10).padEnd(8, '0');
+  const s = String(seq).padStart(4, '0');
+  return `${prefix}-${(Date.now().toString(36) + s).slice(-8)}-${rand}`;
+}
+
+// Decode a task's buffered chunks for display. Buffer chunks (Bash) are UTF-8;
+// string chunks (Agent/AgentSwarm) are already text.
+function decodeTaskOutput(chunks) {
+  const list = chunks || [];
+  if (!list.length) return '';
+  const allStrings = list.every((c) => typeof c === 'string');
+  if (allStrings) return list.join('');
+  try { return Buffer.concat(list.map((c) => (Buffer.isBuffer(c) ? c : Buffer.from(String(c))))).toString('utf8'); }
+  catch { return list.map((c) => String(c)).join(''); }
+}
+
+// The task store lives on the agent ctx (`ctx.tasks`), so every tool and the TUI
+// see the same map.
+function store(ctx) {
+  if (!ctx) return {};
+  if (!ctx.tasks) ctx.tasks = {};
+  return ctx.tasks;
+}
+
+/**
+ * Register a task. `kind` selects the payload group; the returned object is the
+ * live record (mutate `status`/`endedAt`/`stopReason` as it runs).
+ *
+ * options:
+ *   description  short human label
+ *   detached     true when it runs in the background (Ctrl+B or run_in_background)
+ *   timeoutMs    optional cap
+ *   command/pid/exitCode            (kind 'process')
+ *   agentId/subagentType/model/thinkingEffort  (kind 'agent')
+ *   questionCount/toolCallId        (kind 'question')
+ *   output       initial output text
+ */
+export function createTask(ctx, kind, options = {}) {
+  const tasks = store(ctx);
+  const prefix = kind === 'process' ? 'bash' : kind === 'agent' ? 'agent' : 'question';
+  const task = {
+    taskId: newTaskId(prefix),
+    kind,
+    description: String(options.description || ''),
+    status: 'running',
+    detached: options.detached !== false,
+    startedAt: Date.now(),
+    endedAt: null,
+    stopReason: undefined,
+    timeoutMs: options.timeoutMs,
+    // Output is buffered here and exposed through `output` below. Kept as chunks
+    // so the decoder can run lazily (a chatty task costs nothing until read).
+    _chunks: options._chunks || [],
+    _bytes: 0,
+  };
+  if (kind === 'process') {
+    task.command = String(options.command || '');
+    task.pid = options.pid || 0;
+    task.exitCode = null;
+  } else if (kind === 'agent') {
+    task.agentId = options.agentId;
+    task.subagentType = options.subagentType;
+    task.model = options.model;
+    task.thinkingEffort = options.thinkingEffort;
+  } else if (kind === 'question') {
+    task.questionCount = options.questionCount || 0;
+    task.toolCallId = options.toolCallId;
+  }
+  // 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
+  //   * an agent/swarm appends strings  -> join
+  // Callers may override this getter when they need a different decoding.
+  Object.defineProperty(task, 'output', {
+    enumerable: true,
+    configurable: true,
+    get() { return decodeTaskOutput(this._chunks); },
+  });
+  tasks[task.taskId] = task;
+  return task;
+}
+
+// Cap retained output per task; a runaway command must not exhaust memory.
+export const MAX_TASK_OUTPUT_BYTES = 2 * 1024 * 1024;
+
+// Append raw bytes/chunks to a task, trimming the oldest past the cap.
+export function appendTaskOutput(task, chunk) {
+  if (!task || chunk == null) return;
+  task._chunks.push(chunk);
+  task._bytes = (task._bytes || 0) + (chunk.length || 0);
+  while (task._bytes > MAX_TASK_OUTPUT_BYTES && task._chunks.length > 1) {
+    task._bytes -= task._chunks[0].length || 0;
+    task._chunks.shift();
+  }
+}
+
+// Settle a task. `status` is one of the kimi statuses; a task that was already
+// stopped keeps 'killed' (mirrors kimi: a deliberate stop must not be relabelled
+// as a failure by the process's non-zero exit).
+export function settleTask(task, status, extra = {}) {
+  if (!task) return;
+  // A task that already reached a TERMINAL state must not be relabelled: a
+  // deliberate stop ('killed') must not turn into 'failed' when the killed
+  // process reports a non-zero exit, and a 'completed' task must not be
+  // downgraded by a late error. Only a still-running task settles.
+  if (isTerminal(task.status)) {
+    if (extra.exitCode !== undefined && task.kind === 'process') task.exitCode = extra.exitCode;
+    return;
+  }
+  task.status = status;
+  task.endedAt = Date.now();
+  if (extra.stopReason !== undefined) task.stopReason = extra.stopReason;
+  if (extra.exitCode !== undefined && task.kind === 'process') task.exitCode = extra.exitCode;
+}
+
+export function listTasks(ctx) {
+  return Object.values(store(ctx));
+}
+
+export function getTask(ctx, id) {
+  return store(ctx)[id] || null;
+}
+
+// Newest-first for display (mirrors kimi's compareTasks: running first, then by
+// most recent activity).
+export function sortedTasks(ctx) {
+  const tasks = listTasks(ctx);
+  return tasks.slice().sort((a, b) => {
+    const at = isTerminal(a.status), bt = isTerminal(b.status);
+    if (at !== bt) return at ? 1 : -1;
+    if (!at) return a.startedAt - b.startedAt;
+    return (b.endedAt || b.startedAt) - (a.endedAt || a.startedAt);
+  });
+}
+
+// Human label for a status, matching kimi's STATUS_LABEL.
+export const STATUS_LABEL = {
+  running: 'running',
+  completed: 'completed',
+  failed: 'failed',
+  timed_out: 'timed out',
+  killed: 'killed',
+  lost: 'lost',
+};
+
+// Colour token for a status (the TUI maps it to a theme colour).
+export function statusColor(status) {
+  if (status === 'running') return 'green';
+  if (status === 'completed') return 'gray';
+  return 'red';
+}

package/src/agent.js

@@ -4,7 +4,9 @@
 
 import { LLM, setToolsList } from './llm.js';
 import { tools, getTool, llmTools } from './tools/index.js';
+import { DELEGATION_TOOLS } from './subagent-types.js';
 import { estimateMessagesTokens } from './term.js';
+import { runHooks } from './plugin.js';
 
 // ---- completion guard --------------------------------------------------------
 // A turn is only complete when the model ends it with an actual answer. Models
@@ -33,10 +35,40 @@ Tools:
 - If a tool fails, read the error and fix your approach. After 2 failed attempts on the same goal, stop and report the blocker.
 - Independent tool calls may run in parallel; never parallelize dependent ones.
 
+Reasoning:
+- Put ALL of your internal reasoning inside <think>...</think> tags, and always emit BOTH the opening
+  and the closing tag. Do not omit the tags, do not abbreviate them, and do not leave the block unclosed.
+- Everything outside <think>...</think> is what the user reads: keep it to the answer itself — what you
+  did and what you found. Never repeat or summarise your reasoning there.
+- Keep the tags exactly as written: <think> and </think>. Do not emit any other variant.
+Acting:
+- Unless the user is explicitly asking for a plan, asking a question about the code, or brainstorming,
+  assume they want the work DONE. Say less and do more: implement the change rather than describing it.
+- Carry the task through implementation and verification in this turn. Do not stop at analysis, at a
+  partial fix, or at a list of things you would do next.
+- New project, no prior context: be ambitious, use your judgement on structure.
+  Existing codebase: be surgical. Touch only what the task needs — no renames, no reorganising,
+  no drive-by fixes.
+- Read the neighbours before you write: match the naming, error handling and comment density you see.
+- Do not re-read a file after editing it, and do not re-run a search you already have results for.
+  A successful edit tool call already proves it worked.
+
 Scope:
 - Do only what was asked. Do not refactor or "improve" unrelated code.
+- Do not fix unrelated bugs or broken tests — mention them instead; they are not yours to change.
 - If the request is ambiguous, ask one short clarifying question.
 - State any assumption you make.
+- Might be a dirty git worktree. Never revert changes you did not make. Never run a destructive command
+  (git reset --hard, git checkout --) unless the user asked for it. If you notice an unexpected change
+  you did not make, stop and ask.
+
+Verifying:
+- Run the narrowest check that exercises your change first, then widen.
+- In auto/yolo mode, run tests and lint yourself without asking.
+- In ask mode, do not burn the user's time on slow test suites mid-task: say what you would run and
+  let them confirm.
+- Do not add tests to a codebase that has none. Do not add a formatter that the project did not configure.
+- If you could not verify something, say so plainly. Do not imply a test passed when you did not run it.
 
 Finishing:
 - Never stop silently after a tool call; end every turn with a written answer in the user's language.
@@ -56,10 +88,18 @@ export class Agent {
     // Ensure the LLM client knows the bare tool specs (the client wraps them per-protocol).
     // A toolFilter (array of tool names) limits which tools are exposed — used
     // by Plan mode (read-only subset) and Focus mode (minimal subset first).
-    const filtered = Array.isArray(cfg.toolFilter) && cfg.toolFilter.length
+    // `cfg.noDelegation` marks this as a SUBAGENT: delegation tools are removed
+    // 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;
+      : tools
+    ).filter((t) => !(cfg.noDelegation && DELEGATION_TOOLS.includes(t.name)));
     setToolsList(filtered);
+    // A block for the direct-call path too: the model can still emit a tool call
+    // for a tool that is not exposed, so refuse it here rather than at execution.
+    this.noDelegation = !!cfg.noDelegation;
     // AbortSignal handed to every tool so a long-running one (Bash) is killed
     // when the user presses Esc / Ctrl-C — otherwise the command keeps running
     // after the turn was interrupted.
@@ -72,6 +112,12 @@ export class Agent {
     this.ctx.onOutput = (chunk) => {
       if (chunk && this._currentToolId) this.onEvent({ type: 'tool_output', id: this._currentToolId, chunk });
     };
+    // `fork` (the Agent tool) snapshots THIS conversation into the subagent. The
+    // tool reads `ctx._parentMessages`, which nothing ever set — so `fork: true`
+    // was accepted and then seeded the subagent with an empty history. Hand the
+    // tool a live getter over this agent's own messages instead of a copy, so the
+    // snapshot is taken at spawn time and reflects everything up to that point.
+    this.ctx._parentMessages = this.messages;
     this.llm = new LLM(cfg);
     this.stopRequested = false;
     this.onApproval = onApproval; // async (toolName, args) => boolean
@@ -97,14 +143,15 @@ export class Agent {
   }
 
   async run() {
+    // Plugin lifecycle: `onTurnStart` fires here and `onTurnEnd` in the finally
+    // block at the end of this method. Both are awaited and both swallow plugin
+    // errors (see runHooks), so a broken plugin cannot abort a turn.
+    await runHooks('onTurnStart', { messages: this.messages });
     let text = '';
     let toolCalls = [];
     let emittedEnd = false;
-    // Reasoning text seen in the current step. A turn that ends with reasoning
-    // but no answer is a truncated turn (see the completion guard below).
     let thought = '';
     let nudges = 0;
-    // True when the most recent iteration still had tool calls pending; used to
     // decide whether running out of steps actually left the turn unfinished.
     let hadToolCallsOnFinalStep = false;
 
@@ -225,7 +272,12 @@ export class Agent {
         }
       }
 
+      // Plugin hooks around the model round-trip. `onBeforeRequest` sees the exact
+      // message array being sent (and may mutate it); `onAfterRequest` fires once
+      // the stream has been consumed.
+      await runHooks('onBeforeRequest', this.messages, this.cfg);
       await this.llm.request(this.messages, handle);
+      await runHooks('onAfterRequest', this.messages, this.cfg);
 
       // An abort ends the turn: keep whatever text arrived, then stop.
       if (this.stopRequested) {
@@ -238,11 +290,17 @@ export class Agent {
       const hasText = !!(text && text.trim());
       const hasCalls = toolCalls.length > 0;
       if (hasText || hasCalls) {
-        this.messages.push({
+        const assistantMsg = {
           role: 'assistant',
           content: hasText ? text : null,
           toolCalls: hasCalls ? toolCalls : undefined,
-        });
+        };
+        this.messages.push(assistantMsg);
+        // Plugin hook: one per assistant message committed to the history. Fired
+        // here (the single point where the model's reply lands) rather than at each
+        // of the eleven `messages.push` sites, so a plugin sees a coherent message
+        // instead of the intermediate bookkeeping pushes.
+        await runHooks('onNewMessage', assistantMsg, this.messages);
       }
 
       // ---- if tool calls exist, execute them ----
@@ -308,6 +366,17 @@ export class Agent {
         }
         
         const tool = getTool(tc.name);
+        // A subagent may not delegate. The tool is not exposed to it, but the model
+        // can still emit a call for a tool it was told about earlier, so refuse it
+        // here with an actionable message instead of running a nested agent.
+        if (this.noDelegation && DELEGATION_TOOLS.includes(tc.name)) {
+          result = `You CAN'T use ${tc.name}: subagents cannot delegate. Do the work yourself and report the result to the agent that started you.`;
+          this.onEvent({ type: 'tool_use', id: tc.id, name: tc.name, args: tc.args });
+          this.messages.push({ role: 'tool', toolCallId: tc.id, content: result });
+          this.onEvent({ type: 'tool_result', id: tc.id, name: tc.name, content: result });
+          allOk = false;
+          continue;
+        }
         if (modeName && !this.cfg.toolFilter.includes(tc.name)) {
           result = `You CAN'T use this tool on ${modeName} Mode. Allowed: ${this.cfg.toolFilter.join(', ')}.`;
           this.onEvent({ type: 'tool_use', id: tc.id, name: tc.name, args: tc.args });
@@ -322,6 +391,10 @@ export class Agent {
         } else {
           if (this.onToolStart) this.onToolStart(tc.name, tc.args);
           this.onEvent({ type: 'tool_use', id: tc.id, name: tc.name, args: tc.args });
+          // Plugin hook: onToolExecute fires BEFORE the tool runs and receives the
+          // mutable args object, so a plugin can inspect or adjust a call. Errors
+          // are swallowed by runHooks — a broken plugin must not break a turn.
+          await runHooks('onToolExecute', tc.name, tc.args, this.ctx);
           try {
             result = await tool.execute(tc.args, this.ctx);
           } catch (err) {
@@ -329,15 +402,27 @@ export class Agent {
             allOk = false;
           }
           this.ctx.lastResult = result;
+          // Plugin hook: onToolResult fires with the tool's output.
+          await runHooks('onToolResult', tc.name, result, this.ctx);
           // Surface the live TODO list so the TUI can render its panel.
           if (tc.name === 'TodoList') {
             this.onEvent({ type: 'todos', todos: this.ctx.todoState || [] });
           }
         }
         this.messages.push({ role: 'tool', toolCallId: tc.id, content: result });
-        this.onEvent({ type: 'tool_result', id: tc.id, name: tc.name, content: result });
+        // An Edit reports the text it replaced on ctx (both the substring and the
+        // line-range path do). Forward it so the TUI can draw the +/- diff: the
+        // line-range mode has no `old_string` in its args, so without this the
+        // edit rendered with no diff at all. Cleared every time so a later tool
+        // cannot inherit a stale diff.
+        this.onEvent({
+          type: 'tool_result', id: tc.id, name: tc.name, content: result,
+          editDiff: this.ctx.lastEditDiff || null,
+        });
+        this.ctx.lastEditDiff = null;
       }
 
+
       // Did THIS iteration still have tool calls? If the loop runs out of budget
       // right after running them, the turn really is unfinished.
       hadToolCallsOnFinalStep = toolCalls.length > 0;
@@ -360,5 +445,13 @@ export class Agent {
       });
     }
     if (!emittedEnd && this.onEvent) this.onEvent({ type: 'done' });
+    // The turn is over, so the inline-reasoning block it may have left open is
+    // abandoned: the NEXT user turn starts a fresh one. Without this, a model that
+    // never wrote its closing tag would leave the following turn's answer classified
+    // as reasoning.
+    if (typeof this.llm.resetThink === 'function') this.llm.resetThink();
+    // Plugin lifecycle: the turn is over (normally, interrupted, or out of steps).
+    // In a finally-equivalent position — every exit path above reaches here.
+    await runHooks('onTurnEnd', { messages: this.messages, stopped: this.stopRequested });
   }
 }

package/src/colors.js

@@ -57,6 +57,13 @@ export const C = {
   reset: '\x1b[0m',
   bold: '\x1b[1m',
   dim: '\x1b[2m',
+  // Italic (SGR 3). Used for the BODY of a reasoning block — the prose reads as
+  // an aside rather than as the answer. Must be closed with SGR 23 (`endItalic`),
+  // NOT with `reset`, because resetting also drops the surrounding dim/gray that
+  // the same row depends on. Terminals without italic fall back to normal text,
+  // so this is a decoration, never load-bearing.
+  italic: '\x1b[3m',
+  endItalic: '\x1b[23m',
   muted: '\x1b[90m',
   teal: TEAL,
   cyan: CYAN,
@@ -74,6 +81,13 @@ export const C = {
   gray: '\x1b[90m',
   white: '\x1b[97m',
   orange: TRUECOLOR ? rgb(255, 140, 0) : '\x1b[38;5;208m',
+  // Cyan pushed slightly toward green — used for the Swarm mode badge so it reads
+  // as its own mode next to Plan (pure cyan) and Focus (blue) while staying in the
+  // theme's blue-green family. 38;5;43 is rgb(0,215,175): red at zero and green
+  // only 40 above blue, i.e. still clearly cyan with a green cast. 38;5;85 was the
+  // first attempt and read as plain GREEN — its red channel is lifted to 95 and
+  // green pins at 255, which is a spring green, not a green-tinted cyan.
+  spring: TRUECOLOR ? rgb(0, 215, 175) : '\x1b[38;5;43m',
   bgRed: '\x1b[41m',
   bgGreen: '\x1b[42m',
   // Selection highlight (mouse text selection) and the scrollbar gutter.