@hncode/hncode 0.6.7 → 0.7.0

package/package.json

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

package/src/ptc-worker.js

@@ -0,0 +1,120 @@
+// The PTC executor's WORKER SIDE — what actually runs the model's code.
+//
+// This file is loaded as a `worker_threads` entry, never imported by the main process. Everything it can reach is
+// what `parentPort` hands it and the globals below: no `require`, no `process` access beyond what is passed in,
+// and no filesystem. The model's code is compiled inside a `vm` context whose only interesting binding is
+// `callTool`, which messages the main thread and waits.
+//
+// WHY A WORKER AND NOT vm ALONE: `vm` is not a security boundary — code in a context can still reach the host
+// through a prototype it was handed. The thread is what makes a runaway loop killable: `worker.terminate()` stops
+// it without the main process ever yielding, which a `while(true)` in `vm.runInContext` would not.
+//
+// The code runs as an ASYNC body, so `await callTool(...)` works exactly as it reads.
+import { parentPort, workerData } from 'node:worker_threads';
+import vm from 'node:vm';
+
+const TOOL_NAMES = Array.isArray(workerData && workerData.toolNames) ? workerData.toolNames : [];
+const TIMEOUT_MS = Number(workerData && workerData.timeoutMs) > 0 ? workerData.timeoutMs : 120000;
+
+let seq = 0;
+const pending = new Map();
+
+/** Ask the main thread to run a tool, and wait for its answer. */
+function callTool(name, args) {
+  const id = ++seq;
+  parentPort.postMessage({ type: 'tool', id, name, args: args == null ? {} : args });
+  return new Promise((resolve, reject) => {
+    pending.set(id, { resolve, reject });
+  });
+}
+
+parentPort.on('message', (m) => {
+  if (!m || m.type !== 'tool_result') return;
+  const p = pending.get(m.id);
+  if (!p) return;
+  pending.delete(m.id);
+  if (m.ok) p.resolve(m.result);
+  else p.reject(new Error(String(m.error || 'tool failed')));
+});
+
+// ---- the sandbox ---------------------------------------------------------------------------------------------
+
+/** Collect printed lines. `print` is what the model reaches for. */
+const out = [];
+const write = (...parts) => {
+  const line = parts.map((p) => {
+    if (typeof p === 'string') return p;
+    try { return JSON.stringify(p); } catch { return String(p); }
+  }).join(' ');
+  // A single line cap keeps a runaway from filling memory before the byte cap is checked.
+  out.push(line.length > 8000 ? line.slice(0, 8000) + '…' : line);
+};
+
+const sandbox = {
+  callTool,
+  print: write,
+  console: { log: write, error: write, warn: write, info: write },
+  JSON,
+  Math,
+  Date,
+  Promise,
+  Array,
+  Object,
+  String,
+  Number,
+  Boolean,
+  Map,
+  Set,
+  RegExp,
+  Error,
+  TypeError,
+  RangeError,
+  isNaN,
+  isFinite,
+  parseInt,
+  parseFloat,
+  // `sleep` is the one timer worth exposing: pacing between calls is a real need, and `setTimeout` would let the
+  // code keep the thread alive past the point where the caller wants an answer.
+  sleep: (ms) => new Promise((r) => setTimeout(r, Math.max(0, Math.min(Number(ms) || 0, 10000)))),
+};
+
+const context = vm.createContext(sandbox, {
+  // No `codeGeneration` from strings inside the sandbox: a `new Function` there would be a second, unreviewed way
+  // in — and the body the model writes is already compiled below.
+  codeGeneration: { strings: false, wasm: false },
+});
+
+async function run(code) {
+  let script;
+  try {
+    script = new vm.Script(`(async () => {\n${code}\n})()`, { filename: 'ptc-sandbox.js' });
+  } catch (e) {
+    return { ok: false, error: `Syntax error: ${e.message}`, output: '' };
+  }
+
+  const timer = setTimeout(() => {
+    parentPort.postMessage({ type: 'timeout', ms: TIMEOUT_MS });
+    process.exit(0);
+  }, TIMEOUT_MS);
+  if (timer.unref) timer.unref();
+
+  try {
+    const value = await script.runInContext(context, { timeout: TIMEOUT_MS });
+    clearTimeout(timer);
+    // The returned value is what `return` produced, if anything; `print` already captured stdout.
+    let returned;
+    if (value !== undefined) {
+      try { returned = typeof value === 'string' ? value : JSON.stringify(value); } catch { returned = String(value); }
+    }
+    return { ok: true, output: out.join('\n'), returned };
+  } catch (e) {
+    clearTimeout(timer);
+    return { ok: false, error: `${e && e.name ? e.name + ': ' : ''}${e && e.message || e}`, output: out.join('\n') };
+  }
+}
+
+parentPort.on('message', async (m) => {
+  if (!m || m.type !== 'run') return;
+  const result = await run(String(m.code || ''));
+  parentPort.postMessage({ type: 'done', result });
+});

package/src/ptc.js

@@ -0,0 +1,141 @@
+// The PTC executor's MAIN side.
+//
+// Owns a worker, forwards the tool calls it makes to the real tool layer, and enforces the limits the sandbox
+// cannot enforce about itself: output size, tool count, and a wall-clock deadline that survives a wedged await.
+//
+// WHY THE TOOL CALLS COME BACK HERE AT ALL: the tools need `ctx` — the workspace, the approval hook, the session
+// — none of which may exist inside the sandbox. The worker sends `{type:'tool', name, args}`, this side runs the
+// real tool through `getTool`, and the result crosses back as data. The model's code never holds a function that
+// can reach the filesystem; it holds a promise that the host fulfils.
+import { Worker } from 'node:worker_threads';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+/** Tools whose results are safe and useful to hand to code, and whose invocation needs no UI. */
+const CALLABLE = new Set([
+  'Read', 'FileLines', 'Glob', 'Grep', 'Git', 'FetchURL', 'WebSearch',
+  'TodoList', 'TaskList', 'TaskOutput', 'Memory', 'ListTeammates', 'TeamTaskList',
+  'ActivateSkill', 'Goal', 'Diagnostics',
+]);
+
+export const DEFAULT_LIMITS = {
+  // A code body that orchestrates twenty calls is already unusual; five hundred is a loop that has gone wrong.
+  maxToolCalls: 500,
+  // What comes back is the whole point of PTC — a cap keeps a runaway `print` from eating the context it saved.
+  maxOutputBytes: 32000,
+  timeoutMs: 120000,
+};
+
+export const CALLABLE_TOOLS = [...CALLABLE];
+
+/**
+ * Run `code` in a sandbox, letting it call the tools in `CALLABLE`.
+ *
+ * @param {string} code An async function BODY. `await callTool(name, args)` is available.
+ * @param {object} ctx The tool context, passed straight through to each tool.
+ * @param {object} [limits] Overrides for `DEFAULT_LIMITS`.
+ * @returns {Promise<{ok: boolean, output: string, returned?: string, error?: string, calls: string[], truncated?: boolean}>}
+ */
+export function runProgrammatic(code, ctx, limits = {}) {
+  const lim = { ...DEFAULT_LIMITS, ...limits };
+  return new Promise((resolve) => {
+    let settled = false;
+    const calls = [];
+    const lines = [];
+    let bytes = 0;
+    let truncated = false;
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(wall);
+      try { worker.terminate(); } catch { /* already gone */ }
+      resolve(result);
+    };
+
+    const worker = new Worker(path.join(here, 'ptc-worker.js'), {
+      workerData: { toolNames: [...CALLABLE], timeoutMs: lim.timeoutMs },
+      // The sandbox needs no stdio and no shared memory.
+      stdout: true,
+      stderr: true,
+    });
+
+    // The wall clock is the OUTER guarantee: if the worker is stuck in a `while(true)` the inner vm timeout can
+    // still fire, but if the main thread is waiting on a tool that never answers, only this one saves us.
+    const wall = setTimeout(() => {
+      finish({ ok: false, error: `timed out after ${lim.timeoutMs}ms`, output: lines.join('\n'), calls });
+    }, lim.timeoutMs + 5000);
+
+    worker.on('message', async (m) => {
+      if (!m) return;
+
+      if (m.type === 'tool') {
+        if (calls.length >= lim.maxToolCalls) {
+          worker.postMessage({ type: 'tool_result', id: m.id, ok: false, error: `tool-call limit reached (${lim.maxToolCalls})` });
+          return;
+        }
+        const name = String(m.name || '');
+        if (!CALLABLE.has(name)) {
+          worker.postMessage({ type: 'tool_result', id: m.id, ok: false, error: `${name} is not callable from code` });
+          return;
+        }
+        // Imported here, not at the top: tools/index.js imports the PTC TOOL, which imports this module — a static
+        // import would close that cycle and read `spec` before it exists.
+        const { getTool } = await import('./tools/index.js');
+        const tool = getTool(name);
+        if (!tool || typeof tool.execute !== 'function') {
+          worker.postMessage({ type: 'tool_result', id: m.id, ok: false, error: `no such tool: ${name}` });
+          return;
+        }
+        calls.push(name);
+        try {
+          const raw = await tool.execute(m.args || {}, ctx);
+          // A media result is structured blocks, not text; code cannot do anything useful with it.
+          const value = (raw && typeof raw === 'object' && Array.isArray(raw.media))
+            ? '[media result omitted]'
+            : (typeof raw === 'string' ? raw : JSON.stringify(raw));
+          worker.postMessage({ type: 'tool_result', id: m.id, ok: true, result: value });
+        } catch (e) {
+          worker.postMessage({ type: 'tool_result', id: m.id, ok: false, error: String((e && e.message) || e) });
+        }
+        return;
+      }
+
+      if (m.type === 'timeout') {
+        finish({ ok: false, error: `timed out after ${lim.timeoutMs}ms`, output: lines.join('\n'), calls });
+        return;
+      }
+
+      if (m.type === 'done') {
+        const r = m.result || {};
+        let output = String(r.output == null ? '' : r.output);
+        // Cap by BYTES, not characters: the model pays for tokens, and a megabyte of ASCII is the worst case.
+        if (Buffer.byteLength(output, 'utf8') > lim.maxOutputBytes) {
+          output = output.slice(0, lim.maxOutputBytes);
+          truncated = true;
+        }
+        finish({
+          ok: !!r.ok,
+          output,
+          returned: r.returned,
+          error: r.error,
+          calls,
+          truncated: truncated || undefined,
+        });
+      }
+    });
+
+    worker.on('error', (e) => {
+      finish({ ok: false, error: String((e && e.message) || e), output: lines.join('\n'), calls });
+    });
+    worker.on('exit', (code) => {
+      // An exit without a `done` is the worker dying: report it rather than hanging the caller for ever.
+      if (!settled) finish({ ok: false, error: `sandbox exited with code ${code}`, output: lines.join('\n'), calls });
+    });
+
+    worker.postMessage({ type: 'run', code: String(code || '') });
+    void bytes;
+  });
+}

package/src/tools/index.js

@@ -24,6 +24,7 @@ import { spec as diagnosticsSpec } from './diagnostics.js';
 import * as memoryMod from './memory.js';
 import * as goalMod from './goal.js';
 import * as activateSkillMod from './activate-skill.js';
+import * as ptcMod from './ptc.js';
 import { pluginTools, pluginToolGeneration } from '../plugin.js';
 
 
@@ -59,6 +60,7 @@ const builtinTools = [
   memoryMod.spec,
   goalMod.spec,
   activateSkillMod.spec,
+  ptcMod.spec,
   ...TEAM_TOOL_SPECS,
 ];
 

package/src/tools/ptc.js

@@ -0,0 +1,91 @@
+/**
+ * ProgrammaticToolCall — let the model orchestrate tools with code instead of one round trip each.
+ *
+ * THE PROBLEM IT SOLVES: a task like "which of these forty files reference the removed symbol" is forty calls,
+ * each with its own inference pass, and every one of those results then sits in the context whether or not it
+ * mattered. The reading is mechanical; only the conclusion is worth the tokens.
+ *
+ * With this tool the model writes the LOOP, and only what it prints comes back. The sandbox holds the forty
+ * results, the filtering and the joining; the conversation holds the six files that matched.
+ *
+ * WHY A SEPARATE TOOL AND NOT `Bash`: a shell would give the model the whole machine and no structure. Here every
+ * call goes back through the tool layer — the same approval rules, the same workspace guard, the same tools —
+ * and the code can only reach the ones on the allowlist. See src/ptc.js for that list, and ptc-worker.js for the
+ * sandbox itself.
+ */
+import { runProgrammatic, CALLABLE_TOOLS } from '../ptc.js';
+
+const DESCRIPTION = [
+  'Orchestrate tools with JavaScript instead of calling them one at a time.',
+  '',
+  'WHEN TO USE IT: work that is a LOOP over tool results, or that needs intermediate data the model should not',
+  'have to read. Reading twenty files to find the three that mention a symbol; checking every changed file for a',
+  'pattern; collecting values from many calls and printing only the ones that matter. The intermediate results',
+  'stay inside the sandbox and never enter the conversation — that is the point.',
+  '',
+  'WHEN NOT TO USE IT: one or two calls, or when you need to READ a result and decide what to do next. Then an',
+  'ordinary tool call is shorter and clearer.',
+  '',
+  'HOW TO WRITE IT: the body of an async function. `await callTool(name, args)` runs a tool and resolves to its',
+  'text result. `print(...)` writes a line to the output; `console.log` is the same. Whatever you `return` is',
+  'appended. Nothing reaches the conversation except what you print or return.',
+  '',
+  'Example:',
+  '```',
+  "const hits = [];",
+  "for (const f of (await callTool('Glob', { pattern: 'src/**/*.js' })).split('\\n').filter(Boolean)) {",
+  "  const text = await callTool('Grep', { pattern: 'oldSymbol', path: f });",
+  "  if (text && !/No matches/.test(text)) hits.push(f);",
+  '}',
+  'print(`${hits.length} files still reference it`);',
+  'print(hits.join(\'\\n\'));',
+  '```',
+  '',
+  `CALLABLE TOOLS: ${CALLABLE_TOOLS.join(', ')}.`,
+  'Anything else is refused — a shell or a write would escape the sandbox\'s purpose.',
+].join('\n');
+
+export const spec = {
+  name: 'ProgrammaticToolCall',
+  description: DESCRIPTION,
+  parameters: {
+    type: 'object',
+    properties: {
+      code: {
+        type: 'string',
+        description: [
+          'The body of an async function. `await callTool(name, args)` calls a tool; `print(x)` emits a line.',
+          'Only what is printed or returned reaches the conversation.',
+        ].join(' '),
+      },
+      purpose: {
+        type: 'string',
+        description: 'One line naming what the code is for, shown in the transcript.',
+      },
+    },
+    required: ['code'],
+  },
+  async execute(args, ctx) {
+    const code = String((args && args.code) || '');
+    if (!code.trim()) return 'Error: `code` is empty.';
+
+    const r = await runProgrammatic(code, ctx);
+    const parts = [];
+
+    if (r.output) parts.push(r.output);
+    if (r.returned != null && String(r.returned).trim()) parts.push(String(r.returned));
+    if (r.truncated) parts.push('[output truncated]');
+
+    if (!r.ok) {
+      // The error goes LAST, after whatever the code managed to print: a partial result plus the reason it
+      // stopped is more useful than the reason alone.
+      parts.push(`Error: ${r.error}`);
+    }
+
+    // How many tools ran is worth stating — it is the saving this feature exists for, and a model that sees 0 is
+    // being told its code never reached a tool.
+    if (r.calls.length) parts.push(`(${r.calls.length} tool call${r.calls.length === 1 ? '' : 's'})`);
+
+    return parts.join('\n') || '(no output)';
+  },
+};

package/src/tui.js

@@ -14140,7 +14140,7 @@ const agents = readAgentsMd(state.cwd || state.workspace || cfg.workspace, state
       // Tools that act ONLY inside the session: the roster, the mailbox, the task list, the memories.
       // `isInsideWorkspace` answers `false` for any tool it does not know, so without this they all asked for
       // approval in yolo — the one mode whose point is not asking.
-      const safeTools = ['Read', 'Grep', 'Glob', 'FetchURL', 'WebSearch', 'TaskOutput', 'TaskList', 'TaskStop', 'TaskWait', 'TodoList', 'Goal', 'ActivateSkill', 'FileLines', 'AgentList', 'AgentMessage', 'AgentInterrupt', 'AgentClose', 'TaskInput', 'SendMessage', 'TeamTaskCreate', 'TeamTaskUpdate', 'TeamTaskList', 'ListTeammates', 'Memory', 'AskUserQuestion'];
+      const safeTools = ['Read', 'Grep', 'Glob', 'FetchURL', 'WebSearch', 'TaskOutput', 'TaskList', 'TaskStop', 'TaskWait', 'TodoList', 'Goal', 'ActivateSkill', 'ProgrammaticToolCall', 'FileLines', 'AgentList', 'AgentMessage', 'AgentInterrupt', 'AgentClose', 'TaskInput', 'SendMessage', 'TeamTaskCreate', 'TeamTaskUpdate', 'TeamTaskList', 'ListTeammates', 'Memory', 'AskUserQuestion'];
       if (rule !== 'ask' && safeTools.includes(toolName)) return true;
       // A read-only SHELL COMMAND (ls/git status/rg/cat …) is as safe as a
       // read-only TOOL, so it runs without a prompt in Ask mode too — the user