@hncode/hncode 0.2.0 → 0.3.1

package/src/tools/tasks.js

@@ -1,126 +1,141 @@
-// TaskList / TaskOutput / TaskStop — manage background Bash tasks spawned with
-// run_in_background.
-
-import cp from 'node:child_process';
-
-export const TaskListSpec = {
-  name: 'TaskList',
-  description: 'List background tasks (from Bash run_in_background). Reports id, status, description.',
-  parameters: { type: 'object', properties: {}, required: [] },
-  async execute(_args, ctx) {
-    const tasks = Object.values(ctx.tasks || {}).sort((a, b) => b.start - a.start);
-    if (tasks.length === 0) return 'No background tasks.';
-    return tasks.map((t) => `#${t.id} [${t.status}] pid=${t.pid} ${t.description || t.command}`).join('\n');
-  },
-};
-
-export const TaskOutputSpec = {
-  name: 'TaskOutput',
-  description: 'Get the output of a background task (Bash run_in_background) by task_id. head_limit caps the lines returned.',
-  parameters: {
-    type: 'object',
-    properties: {
-      task_id: { type: 'string', description: 'Task id returned when the task was started.' },
-      head_limit: { type: 'integer', minimum: 0, description: 'Max output lines returned.' },
-    },
-    required: ['task_id'],
-  },
-  async execute(args, ctx) {
-    const t = (ctx.tasks || {})[args.task_id];
-    if (!t) return `No such task: ${args.task_id}`;
-    const lines = t.output ? t.output.split('\n').filter((l) => l.length > 0) : [];
-    const capped = args.head_limit ? lines.slice(0, args.head_limit) : lines;
-    const tail = lines.length > (capped.length);
-    let out = `#${t.id} [${t.status}] (pid ${t.pid})\n${capped.join('\n')}`;
-    if (tail) out += `\n... [${lines.length - capped.length} more lines; use head_limit]`;
-    return out;
-  },
-};
-
-export const TaskStopSpec = {
-  name: 'TaskStop',
-  description: 'Stop a running background task (Bash run_in_background) by task_id. Use only when the task must be cancelled.',
-  parameters: {
-    type: 'object',
-    properties: {
-      task_id: { type: 'string', description: 'Background task id to stop.' },
-      reason: { type: 'string', description: 'Short reason recorded on stop.' },
-    },
-    required: ['task_id'],
-  },
-  async execute(args, ctx) {
-    const t = (ctx.tasks || {})[args.task_id];
-    if (!t) return `No such task: ${args.task_id}`;
-    if (t.status !== 'running') return `Task ${t.id} is not running (status: ${t.status}).`;
-    const reason = args.reason || 'Stopped by TaskStop';
-    try {
-      if (process.platform === 'win32' && t.pid) {
-        try { cp.spawnSync('taskkill', ['/pid', String(t.pid), '/t', '/f'], { stdio: 'ignore' }); } catch {}
-      } else if (t.pid) {
-        try { process.kill(t.pid, 'SIGTERM'); } catch {}
-      }
-    } catch (e) {
-      return `Failed to stop ${t.id}: ${e.message}`;
-    }
-    t.status = 'stopped';
-    t.stopReason = reason;
-    t.end = Date.now();
-    return `Stopped task ${t.id}. reason: ${reason}`;
-  },
-};
-
-// WaitFor — block until a background task finishes (or the timeout elapses).
-// Mirrors kimi-code's task-wait: a timeout is not an error; the result lists
-// the tasks still running so the caller can wait again.
-export const TaskWaitSpec = {
-  name: 'TaskWait',
-  description: 'Wait for background tasks (Bash run_in_background) to finish, timeout in seconds (1-600). With task_id, waits for that task; without it, returns when any running task finishes. A timeout is not an error; still-running tasks are listed, so you may call it again.',
-  parameters: {
-    type: 'object',
-    properties: {
-      timeout: { type: 'integer', minimum: 1, maximum: 600, description: 'Max seconds to wait (1-600).' },
-      task_id: { type: 'string', description: 'Task id to wait for; omit to wait for any running task.' },
-    },
-    required: ['timeout'],
-  },
-  async execute(args, ctx) {
-    const tasks = ctx.tasks || {};
-    const target = args.task_id ? tasks[args.task_id] : null;
-    if (args.task_id && !target) return `No such task: ${args.task_id}`;
-    const secs = Math.max(1, Math.min(600, Number(args.timeout) || 1));
-    const deadline = Date.now() + secs * 1000;
-    const signal = ctx && ctx.signal;
-
-    const isDone = (t) => t && t.status !== 'running';
-    const anyRunning = () => Object.values(tasks).some((t) => t.status === 'running');
-
-    // Nothing to wait for at call time.
-    if (args.task_id) {
-      if (isDone(target)) return `Task ${target.id} already ${target.status}${target.code !== undefined ? ` (exit ${target.code})` : ''}.`;
-    } else if (!anyRunning()) {
-      return 'No background tasks are running.';
-    }
-
-    await new Promise((resolve) => {
-      const tick = setInterval(() => {
-        const done = args.task_id ? isDone(target) : !anyRunning();
-        if (done || Date.now() >= deadline || (signal && signal.aborted)) {
-          clearInterval(tick);
-          resolve();
-        }
-      }, 100);
-    });
-
-    if (signal && signal.aborted) return 'Interrupted by user';
-    const still = Object.values(tasks).filter((t) => t.status === 'running');
-    if (args.task_id) {
-      if (isDone(target)) {
-        return `Task ${target.id} finished: ${target.status}${target.code !== undefined ? ` (exit ${target.code})` : ''}${target.stopReason ? ` — ${target.stopReason}` : ''}.`;
-      }
-      return `Task ${target.id} still running after ${secs}s.`;
-    }
-    if (!still.length) return 'All background tasks have finished.';
-    const list = still.map((t) => `#${t.id} ${t.description || t.command}`).join('; ');
-    return `Timeout after ${secs}s; still running: ${list}`;
-  },
-};
+// TaskList / TaskOutput / TaskStop / TaskWait — manage background tasks spawned
+// by Bash (run_in_background) and Agent (run_in_background). The task records
+// live in the shared registry (src/agent-task.js), so the CLI tools and the
+// /tasks panel read exactly the same data.
+
+import cp from 'node:child_process';
+import { isTerminal, settleTask, STATUS_LABEL } from '../agent-task.js';
+
+function taskLine(t) {
+  const extra = t.stopReason ? ` (${t.stopReason})` : '';
+  const label = STATUS_LABEL[t.status] || t.status;
+  const what = t.kind === 'process' ? (t.description || t.command) : t.description;
+  return `#${t.taskId} [${label}${extra}] pid=${t.pid || '-'} ${what}`;
+}
+
+export const TaskListSpec = {
+  name: 'TaskList',
+  description: 'List background tasks (from Bash or Agent run_in_background). Reports task id, status, description.',
+  parameters: { type: 'object', properties: {}, required: [] },
+  async execute(_args, ctx) {
+    const tasks = Object.values(ctx.tasks || {}).sort((a, b) => b.startedAt - a.startedAt);
+    if (tasks.length === 0) return 'No background tasks.';
+    return tasks.map(taskLine).join('\n');
+  },
+};
+
+export const TaskOutputSpec = {
+  name: 'TaskOutput',
+  description: 'Get the output of a background task by task_id. head_limit caps the lines returned.',
+  parameters: {
+    type: 'object',
+    properties: {
+      task_id: { type: 'string', description: 'Task id returned when the task was started.' },
+      head_limit: { type: 'integer', minimum: 0, description: 'Max output lines returned.' },
+    },
+    required: ['task_id'],
+  },
+  async execute(args, ctx) {
+    const t = (ctx.tasks || {})[args.task_id];
+    if (!t) return `No such task: ${args.task_id}`;
+    const text = t.output || '';
+    const lines = text ? text.split('\n').filter((l) => l.length > 0) : [];
+    const capped = args.head_limit ? lines.slice(0, args.head_limit) : lines;
+    const tail = lines.length > capped.length;
+    const label = STATUS_LABEL[t.status] || t.status;
+    const head = `#${t.taskId} [${label}] (pid ${t.pid || '-'})`;
+    let out = capped.length ? `${head}\n${capped.join('\n')}` : `${head}\n(no output yet)`;
+    if (tail) out += `\n... [${lines.length - capped.length} more lines; use head_limit]`;
+    return out;
+  },
+};
+
+export const TaskStopSpec = {
+  name: 'TaskStop',
+  description: 'Stop a running background task by task_id. Use only when the task must be cancelled.',
+  parameters: {
+    type: 'object',
+    properties: {
+      task_id: { type: 'string', description: 'Background task id to stop.' },
+      reason: { type: 'string', description: 'Short reason recorded on stop.' },
+    },
+    required: ['task_id'],
+  },
+  async execute(args, ctx) {
+    const t = (ctx.tasks || {})[args.task_id];
+    if (!t) return `No such task: ${args.task_id}`;
+    if (isTerminal(t.status)) return `Task ${t.taskId} already ${STATUS_LABEL[t.status] || t.status}.`;
+    const reason = args.reason || 'Stopped by TaskStop';
+    try {
+      // An agent task aborts through its controller; a process is killed.
+      if (t.kind === 'agent' && typeof t._abort === 'function') {
+        t._abort();
+      } else if (t.pid) {
+        if (process.platform === 'win32') {
+          try { cp.spawnSync('taskkill', ['/pid', String(t.pid), '/t', '/f'], { stdio: 'ignore' }); } catch {}
+        } else {
+          try { process.kill(t.pid, 'SIGTERM'); } catch {}
+        }
+      }
+    } catch (e) {
+      return `Failed to stop ${t.taskId}: ${e.message}`;
+    }
+    // 'killed' — a deliberate stop, distinct from a failure (kimi's vocabulary).
+    settleTask(t, 'killed', { stopReason: reason });
+    return `Stopped task ${t.taskId}. reason: ${reason}`;
+  },
+};
+
+// Wait for background tasks to finish. A timeout is not an error; the result
+// lists the tasks still running so the caller can wait again.
+export const TaskWaitSpec = {
+  name: 'TaskWait',
+  description: 'Wait for background tasks to finish, timeout in seconds (1-600). With task_id, waits for that task; without it, returns when any running task finishes. A timeout is not an error; still-running tasks are listed, so you may call it again.',
+  parameters: {
+    type: 'object',
+    properties: {
+      timeout: { type: 'integer', minimum: 1, maximum: 600, description: 'Max seconds to wait (1-600).' },
+      task_id: { type: 'string', description: 'Task id to wait for; omit to wait for any running task.' },
+    },
+    required: ['timeout'],
+  },
+  async execute(args, ctx) {
+    const tasks = ctx.tasks || {};
+    const target = args.task_id ? tasks[args.task_id] : null;
+    if (args.task_id && !target) return `No such task: ${args.task_id}`;
+    const secs = Math.max(1, Math.min(600, Number(args.timeout) || 1));
+    const deadline = Date.now() + secs * 1000;
+    const signal = ctx && ctx.signal;
+
+    const isDone = (t) => t && isTerminal(t.status);
+    const anyRunning = () => Object.values(tasks).some((t) => t.status === 'running');
+
+    if (args.task_id) {
+      if (isDone(target)) return `Task ${target.taskId} already ${STATUS_LABEL[target.status] || target.status}${target.exitCode != null ? ` (exit ${target.exitCode})` : ''}.`;
+    } else if (!anyRunning()) {
+      return 'No background tasks are running.';
+    }
+
+    await new Promise((resolve) => {
+      const tick = setInterval(() => {
+        const done = args.task_id ? isDone(target) : !anyRunning();
+        if (done || Date.now() >= deadline || (signal && signal.aborted)) {
+          clearInterval(tick);
+          resolve();
+        }
+      }, 100);
+    });
+
+    if (signal && signal.aborted) return 'Interrupted by user';
+    const still = Object.values(tasks).filter((t) => t.status === 'running');
+    if (args.task_id) {
+      if (isDone(target)) {
+        return `Task ${target.taskId} finished: ${STATUS_LABEL[target.status] || target.status}${target.exitCode != null ? ` (exit ${target.exitCode})` : ''}${target.stopReason ? ` — ${target.stopReason}` : ''}.`;
+      }
+      return `Task ${target.taskId} still running after ${secs}s.`;
+    }
+    if (!still.length) return 'All background tasks have finished.';
+    const list = still.map((t) => `#${t.taskId} ${t.description || t.command || ''}`).join('; ');
+    return `Timeout after ${secs}s; still running: ${list}`;
+  },
+};

package/src/tools/todo.js

@@ -3,7 +3,21 @@
 
 export const spec = {
   name: 'TodoList',
-  description: 'Track multi-step work. Pass the COMPLETE list; it replaces the current one. Items: title + status (pending | in_progress | done).',
+  description: `Track multi-step work. Pass the COMPLETE list; it replaces the current one. Items: title + status (pending | in_progress | done).
+
+When to use it:
+- Non-trivial work with several ordered steps, or a request that asks for more than one thing.
+- NOT for a straightforward task you can finish in a step or two, and never as a single-item list.
+
+Maintaining the list:
+- Keep exactly ONE item in_progress at a time until everything is done.
+- Never move an item straight from pending to done: set it to in_progress first, so the list reflects
+  what is actually happening. Do not tick off several items in one update after the fact.
+- Step titles are short (5-7 words), one line each.
+- Update the list as you go, before starting the next step, not in a batch at the end.
+- If your understanding changes, replace the whole list with the corrected one and say why.
+- Finish with every item done, or explicitly say which you abandoned and why. Do not leave the list stale.
+- Do not repeat the list back to the user after updating it — the UI already shows it.`,
   parameters: {
     type: 'object',
     properties: {
@@ -23,7 +37,20 @@ export const spec = {
     required: ['todos'],
   },
   async execute(args, ctx) {
-    ctx.todoState = args.todos.map((t) => ({ title: String(t.title), status: t.status || 'pending' }));
+    // `todos` is required, but a missing or mistyped value must not throw: an
+    // uncaught error here aborts the whole turn. Return a message the model can
+    // act on, like every other tool.
+    if (!Array.isArray(args.todos)) {
+      return 'Error: `todos` must be an array of { title, status }.';
+    }
+    const VALID = ['pending', 'in_progress', 'done'];
+    const badStatus = args.todos.find((t) => t && t.status != null && !VALID.includes(t.status));
+    if (badStatus) {
+      return `Error: invalid status ${JSON.stringify(badStatus.status)}; use one of ${VALID.join(' | ')}.`;
+    }
+    const empty = args.todos.find((t) => !t || typeof t.title !== 'string' || !t.title.trim());
+    if (empty) return 'Error: every todo needs a non-empty `title`.';
+    ctx.todoState = args.todos.map((t) => ({ title: String(t.title).trim(), status: t.status || 'pending' }));
     return render(ctx.todoState);
   },
 };

package/src/tools/utils.js

@@ -13,7 +13,17 @@ export function truncateBuf(buf) {
   }
   const s = String(buf);
   if (s.length <= MAX_OUTPUT_BYTES) return s;
-  return s.slice(0, MAX_OUTPUT_BYTES) + `\n...[truncated ${s.length - MAX_OUTPUT_BYTES} chars]`;
+  // The cap is a BYTE budget, but `s.length` is UTF-16 code units. Slicing by
+  // code units both under-counts non-ASCII (a 3-byte CJK char costs 1 unit)
+  // and can split a surrogate pair, emitting a lone half. Truncate by BYTES
+  // and back off to the nearest code-point boundary.
+  const bytes = Buffer.byteLength(s, 'utf8');
+  if (bytes <= MAX_OUTPUT_BYTES) return s;
+  const cut = Buffer.from(s, 'utf8').subarray(0, MAX_OUTPUT_BYTES).toString('utf8');
+  // A trailing lone surrogate (from a split pair) is dropped by decoding; the
+  // replacement char U+FFFD at the tail is also stripped so the marker is clean.
+  const safe = cut.endsWith('\uFFFD') ? cut.slice(0, -1) : cut;
+  return safe + `\n...[truncated ${bytes - MAX_OUTPUT_BYTES} bytes]`;
 }
 
 // Expand ~ and map Git-Bash /c/x -> C:\x style paths, then resolve against cwd.