@hncode/hncode 0.3.2 → 0.3.4

package/src/hooks.js

@@ -0,0 +1,247 @@
+// Shell-command hooks — user-configured commands run at lifecycle events,
+// mirroring Claude Code's `hooks` feature.
+//
+// Config lives in ~/.hncode/hooks.json (and an optional per-project
+// <workspace>/.hncode/hooks.json that is merged on top):
+//
+//   {
+//     "hooks": {
+//       "PreToolUse":  [{ "matcher": "Edit|Write", "command": "npm run lint" }],
+//       "PostToolUse": [{ "matcher": "Edit",        "command": "npx prettier --write $FILE" }],
+//       "UserPromptSubmit": [{ "command": "echo submitting" }],
+//       "SessionStart": [{ "command": "git fetch --quiet" }],
+//       "Stop":         [{ "command": "echo turn done >> ~/turns.log" }]
+//     }
+//   }
+//
+// Each entry runs the command with the shell (bash on POSIX, pwsh on Windows).
+// The event payload is passed as JSON on stdin and, for convenience, projected
+// into environment variables the command can read directly:
+//
+//   HNCODE_EVENT            event name (PreToolUse, …)
+//   HNCODE_TOOL_NAME        tool name (tool events only)
+//   HNCODE_TOOL_ARGS        JSON of the tool args (tool events only)
+//   HNCODE_FILE             best-effort path argument (tool events only)
+//   HNCODE_PROMPT           the user's prompt (UserPromptSubmit)
+//   HNCODE_CWD              working directory the command runs in
+//
+// Exit codes: 0 = continue. For PreToolUse, a NON-zero exit BLOCKS the tool and
+// its stderr (or stdout) becomes the message the model sees. For every other
+// event a failure is only logged, never fatal — a broken hook must not stop a
+// turn. Hooks are best-effort and time-bounded (see HOOK_TIMEOUT_MS).
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import cp from 'node:child_process';
+
+// Events the core emits. Kept explicit so a typo in config is reported instead
+// of silently never firing.
+export const HOOK_EVENTS = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PostToolUse',
+  'Stop',
+  'PreCompact',
+];
+
+// A hook that hangs must not hang the agent. 60s is generous for a formatter or
+// a lint pass and still bounded.
+export const HOOK_TIMEOUT_MS = 60 * 1000;
+
+export function globalHooksFile() {
+  return process.env.HNCODE_HOOKS_FILE || path.join(os.homedir(), '.hncode', 'hooks.json');
+}
+export function projectHooksFile(workspace) {
+  return path.join(workspace || process.cwd(), '.hncode', 'hooks.json');
+}
+
+// Parse one hooks file. Returns { hooks: {event: [entry]}, errors: [string] }.
+// A malformed file yields empty hooks and a recorded error, never a throw.
+function readHooksFile(file) {
+  const out = { hooks: {}, errors: [] };
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return out; }
+  let doc;
+  try { doc = JSON.parse(text); } catch (e) {
+    out.errors.push(`${file}: invalid JSON (${e.message})`);
+    return out;
+  }
+  const raw = (doc && doc.hooks) || {};
+  for (const [event, list] of Object.entries(raw)) {
+    if (!HOOK_EVENTS.includes(event)) { out.errors.push(`${file}: unknown event "${event}"`); continue; }
+    const entries = Array.isArray(list) ? list : [list];
+    const clean = [];
+    for (const e of entries) {
+      if (!e || typeof e !== 'object' || typeof e.command !== 'string' || !e.command.trim()) {
+        out.errors.push(`${file}: ${event} entry needs a non-empty "command"`);
+        continue;
+      }
+      clean.push({
+        command: e.command,
+        matcher: typeof e.matcher === 'string' ? e.matcher : '',
+        timeoutMs: Number.isFinite(e.timeout) ? Math.max(1, e.timeout) * 1000 : HOOK_TIMEOUT_MS,
+        source: file,
+      });
+    }
+    if (clean.length) out.hooks[event] = clean;
+  }
+  return out;
+}
+
+// Merge global + project hooks. Project entries run AFTER global ones so a
+// project can add to (not replace) the user's setup.
+export function loadHooks(workspace) {
+  const merged = {};
+  const errors = [];
+  const files = workspace
+    ? [globalHooksFile(), projectHooksFile(workspace)]
+    : [globalHooksFile()];
+  const seen = new Set();
+  for (const f of files) {
+    const abs = path.resolve(f);
+    if (seen.has(abs)) continue;         // global === project (workspace is ~)
+    seen.add(abs);
+    const { hooks, errors: errs } = readHooksFile(abs);
+    errors.push(...errs);
+    for (const [ev, list] of Object.entries(hooks)) {
+      merged[ev] = (merged[ev] || []).concat(list);
+    }
+  }
+  return { hooks: merged, errors };
+}
+
+// Does this entry apply to `toolName`? An empty matcher matches everything; a
+// non-empty one is a case-insensitive alternation of exact names (Claude Code's
+// `Edit|Write` form).
+export function matcherApplies(matcher, toolName) {
+  if (!matcher) return true;
+  if (!toolName) return true;
+  const name = String(toolName);
+  return matcher.split('|').map((s) => s.trim()).filter(Boolean)
+    .some((m) => m.toLowerCase() === name.toLowerCase());
+}
+
+// The path-ish argument of a tool call, for HNCODE_FILE. Best-effort: it only
+// needs to help a formatter/linter, not to be authoritative.
+function fileArgFor(args) {
+  if (!args || typeof args !== 'object') return '';
+  for (const k of ['path', 'file_path', 'filePath', 'file']) {
+    if (typeof args[k] === 'string' && args[k]) return args[k];
+  }
+  return '';
+}
+
+// Build the environment for a hook invocation from the event payload.
+export function hookEnv(event, payload, cwd) {
+  const p = payload || {};
+  const env = { ...process.env, HNCODE_EVENT: event, HNCODE_CWD: cwd || process.cwd() };
+  if (p.toolName) env.HNCODE_TOOL_NAME = String(p.toolName);
+  if (p.toolArgs !== undefined) env.HNCODE_TOOL_ARGS = JSON.stringify(p.toolArgs);
+  const f = fileArgFor(p.toolArgs);
+  if (f) env.HNCODE_FILE = f;
+  if (p.prompt !== undefined) env.HNCODE_PROMPT = String(p.prompt);
+  return env;
+}
+
+function shellCommand() {
+  if (process.platform === 'win32') return { bin: 'pwsh', flag: '-Command' };
+  return { bin: '/bin/sh', flag: '-c' };
+}
+
+// Run ONE hook entry. Resolves to
+//   { ok: true, stdout, stderr, exitCode }            — command exited 0
+//   { ok: false, blocked: bool, message, ... }        — non-zero / timeout
+// Never rejects: a hook failure is data, not an exception.
+export function runHookCommand(entry, event, payload, cwd) {
+  return new Promise((resolve) => {
+    const { bin, flag } = shellCommand();
+    let child;
+    try {
+      child = cp.spawn(bin, [flag, entry.command], {
+        cwd: cwd || process.cwd(),
+        env: hookEnv(event, payload, cwd),
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } catch (e) {
+      resolve({ ok: false, blocked: false, message: `could not start: ${e.message}`, exitCode: null });
+      return;
+    }
+    let out = '', err = '';
+    let done = false;
+    const finish = (res) => { if (!done) { done = true; resolve(res); } };
+    const timer = setTimeout(() => {
+      try { child.kill(); } catch {}
+      finish({ ok: false, blocked: event === 'PreToolUse', message: `timed out after ${entry.timeoutMs / 1000}s`, exitCode: null });
+    }, entry.timeoutMs);
+
+    if (child.stdout) child.stdout.on('data', (d) => { out += d.toString(); });
+    if (child.stderr) child.stderr.on('data', (d) => { err += d.toString(); });
+    child.on('error', (e) => { clearTimeout(timer); finish({ ok: false, blocked: false, message: e.message, exitCode: null }); });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (code === 0) finish({ ok: true, stdout: out, stderr: err, exitCode: 0 });
+      else finish({
+        ok: false,
+        blocked: event === 'PreToolUse',
+        message: (code === null ? 'terminated' : `exit ${code}`),
+        stdout: out, stderr: err, exitCode: code,
+      });
+    });
+    // Feed the payload as JSON on stdin (some hooks prefer parsing it).
+    try {
+      if (child.stdin) {
+        child.stdin.end(JSON.stringify({ event, ...(payload || {}) }));
+      }
+    } catch { /* stdin already gone: the env vars are still available */ }
+  });
+}
+
+// Run every hook for `event`. Returns
+//   { blocked, reason, results: [...] }
+// `blocked` is true only when a PreToolUse hook failed — that is the one event
+// whose exit code changes control flow (the tool must not run).
+export async function runShellHooks(config, event, payload, cwd) {
+  const list = (config && config.hooks && config.hooks[event]) || [];
+  if (!list.length) return { blocked: false, reason: '', results: [] };
+  // Tool events respect their matcher: a `matcher: "Edit"` hook must fire only
+  // for Edit, for BOTH PreToolUse and PostToolUse. Applying it to PreToolUse
+  // alone made a PostToolUse hook run on every tool — a "format after edit" hook
+  // ran after reads and searches too.
+  const isToolEvent = event === 'PreToolUse' || event === 'PostToolUse';
+  const results = [];
+  for (const entry of list) {
+    if (isToolEvent && !matcherApplies(entry.matcher, payload && payload.toolName)) continue;
+    const r = await runHookCommand(entry, event, payload, cwd);
+    results.push({ entry, ...r });
+    if (!r.ok) {
+      // The message the model sees: prefer stderr, fall back to stdout.
+      const msg = (r.stderr || r.stdout || r.message || 'hook failed').trim();
+      if (event === 'PreToolUse') {
+        return { blocked: true, reason: msg || 'blocked by a PreToolUse hook', results };
+      }
+      // Other events: log only, keep going.
+      try { console.error(`[hncode-hook] ${event} (${entry.source}): ${msg}`); } catch {}
+    }
+  }
+  return { blocked: false, reason: '', results };
+}
+
+// Human-readable summary for /hooks.
+export function describeHooks(config) {
+  const hooks = (config && config.hooks) || {};
+  const lines = [];
+  const total = Object.values(hooks).reduce((a, l) => a + l.length, 0);
+  if (!total) return ['No hooks configured.', '', `Global file:  ${globalHooksFile()}`, `Project file: ${projectHooksFile(process.cwd())}`];
+  for (const ev of HOOK_EVENTS) {
+    const list = hooks[ev];
+    if (!list || !list.length) continue;
+    lines.push(`${ev}:`);
+    for (const e of list) {
+      lines.push(`  ${e.matcher ? `[${e.matcher}] ` : ''}${e.command}`);
+      lines.push(`      (${e.source})`);
+    }
+  }
+  return lines;
+}

package/src/index.js

@@ -9,6 +9,7 @@ import { Agent, SYSTEM_PROMPT } from './agent.js';
 import { llmTools } from './tools/index.js';
 import { setToolsList } from './llm.js';
 import { localVersion } from './version.js';
+import { EXIT, FORMATS, isValidFormat, buildResult, exitCodeFor, resultLine, createRunTracker, trackEvent, finalReply } from './ci.js';
 
 // The version shown by `hncode -V` and the help banner. Read from package.json
 // (via version.js) so it can never drift from the published version again.
@@ -29,7 +30,11 @@ Options:
   --auto                        Never ask; everything runs automatically.
   -m, --model <model>           Model alias to use for this invocation.
   -p, --prompt <prompt>         Run one prompt non-interactively and print the reply.
-  --output-format <format>      Output format for prompt mode: text (default) or stream-json.
+  --output-format <format>      Prompt mode output: text (default), json, or stream-json.
+                                json prints one result object; stream-json streams events then a result.
+                                Exit code reflects the outcome: 0 ok, 1 failure, 2 config, 3 no answer, 4 interrupted.
+  --control                     Expose a local control socket (prompt/status/interrupt) while the TUI runs.
+  --control <path>              Same, at an explicit socket path.
   --plan                        Start in plan mode (research only, no writes).
   --add-dir <dir>               Add an additional workspace directory. Repeatable.
   -h, --help                    Show help.
@@ -40,6 +45,12 @@ Commands:
   doctor config [path]          Validate a config.toml (default: merged config).
   init                          Create ~/.hncode/config.toml with defaults.
   export [id]                   Export a session to ~/.hncode/export/<id>.json.
+  control status                Ask a running session (started with --control) for its status.
+  control prompt <text>         Queue a prompt on a running session.
+  control interrupt             Interrupt the running turn.
+  hooks list                    Show configured shell hooks.
+  skills list                   List installed skills.
+  mcp list                      Show configured MCP servers.
 `;
 
 function printHelp() { process.stdout.write(HELP); }
@@ -55,7 +66,7 @@ export function parseArgs(argv) {
       if (eq >= 0) { key = a.slice(2, eq); val = a.slice(eq + 1); }
       else { key = a.slice(2); val = null; }
       if (key === 'resume') key = 'session'; // `--resume <id>` is an alias for `--session <id>`
-      if (['session'].includes(key) && val === null) { const nx = argv[i + 1]; out[key] = nx !== undefined && !nx.startsWith('-') ? (i++, nx) : true; }
+      if (['session', 'control'].includes(key) && val === null) { const nx = argv[i + 1]; out[key] = nx !== undefined && !nx.startsWith('-') ? (i++, nx) : true; }
 else if (key === 'model' || key === 'prompt' || key === 'output-format' || key === 'add-dir') {
         if (val === null) {
           const nx = argv[i + 1];
@@ -177,14 +188,42 @@ const SUBCOMMANDS = {
   'doctor': { 'config': cmdDoctorConfig },
   'init': cmdInit,
   'export': cmdExport,
+  'control': {
+    // Subcommands pass only positional[2] to their handler, so bind the op.
+    'status': (rest) => cmdControl('status', rest),
+    'prompt': (rest) => cmdControl('prompt', rest),
+    'interrupt': (rest) => cmdControl('interrupt', rest),
+  },
 };
 
+// ---- control (talk to a running --control session) --------------------------
+// `hncode control status|prompt|interrupt` — the client half of the control
+// socket the TUI opens with --control. Prints the JSON reply so a script can
+// parse it; exits non-zero when the running session could not be reached.
+async function cmdControl(sub, arg) {
+  const { sendControl } = await import('./ci.js');
+  const op = sub || 'status';
+  if (!['status', 'prompt', 'interrupt'].includes(op)) {
+    console.error(`unknown control op: ${op}. Use status | prompt <text> | interrupt.`);
+    return 1;
+  }
+  const req = { op };
+  if (op === 'prompt') {
+    const text = String(arg || '').trim();
+    if (!text) { console.error('control prompt requires text.'); return 1; }
+    req.text = text;
+  }
+  const res = await sendControl(req, { path: process.env.HNCODE_CONTROL_SOCKET || undefined });
+  console.log(JSON.stringify(res));
+  return res && res.ok ? 0 : 1;
+}
+
 // ---- headless prompt mode ----
 async function runPrompt({ cfg, prompt, format, session, modelArg }) {
   cfg = resolveModelArg(cfg, modelArg);
   if (!cfg.apiKey) {
     console.error('hncode: no api_key configured. Set HNCODE_API_KEY or configure a provider first. Run `hncode doctor config` to check.');
-    return 2;
+    return EXIT.CONFIG;
   }
   const messages = [];
   if (session && session.messages) for (const m of session.messages.slice(-30)) messages.push(m);
@@ -195,19 +234,28 @@ async function runPrompt({ cfg, prompt, format, session, modelArg }) {
   if (personal) sysText += '\n\n' + personal;
   messages.push({ role: 'system', content: sysText });
   const saved = session || { id: sess.newId(), title: prompt.slice(0, 60), workspace: path.resolve(process.cwd()), model: cfg.model, createdAt: Date.now(), messages: [] };
+  const tracker = createRunTracker();
+  const startedAt = Date.now();
+  let fatal = null;
   const agent = new Agent({
     cfg,
     messages,
     // Uncapped: run until the model finishes (see agent.js).
     onEvent: (e) => {
-      if (format === 'stream-json') {
-        if (e.type === 'context') return; // TUI-only gauge; not part of the JSON stream
-        const line = { type: e.type };
-        if (e.text) line.text = e.text;
-        if (e.name) line.name = e.name;
-        if (e.id) line.id = e.id;
-        if (e.content != null) line.content = e.content;
-        process.stdout.write(JSON.stringify(line) + '\n');
+      trackEvent(tracker, e);
+      if (e.type === 'error') fatal = (e.error && e.error.message) || String(e.error);
+      if (format === 'stream-json' || format === 'json') {
+        // `json` mode keeps stdout clean for the final envelope, so events go to
+        // stderr there. `stream-json` is the streaming contract: one event/line.
+        if (format === 'stream-json') {
+          if (e.type === 'context') return; // TUI-only gauge; not part of the stream
+          const line = { type: e.type };
+          if (e.text) line.text = e.text;
+          if (e.name) line.name = e.name;
+          if (e.id) line.id = e.id;
+          if (e.content != null) line.content = e.content;
+          process.stdout.write(JSON.stringify(line) + '\n');
+        }
       } else if (e.type === 'data') {
         process.stdout.write(e.text);
       }
@@ -216,8 +264,30 @@ async function runPrompt({ cfg, prompt, format, session, modelArg }) {
   saved.messages = messages;
   await agent.run();
   sess.saveSession(saved);
-  if (format !== 'stream-json') process.stdout.write('\n');
-  return 0;
+
+  const reply = finalReply(messages, tracker.text);
+  const result = buildResult({
+    reply,
+    toolCalls: tracker.toolCalls,
+    files: tracker.files,
+    error: fatal || (tracker.errors.length ? tracker.errors[tracker.errors.length - 1] : null),
+    stopped: !!agent.stopRequested,
+    durationMs: Date.now() - startedAt,
+    model: cfg.model,
+    sessionId: saved.id,
+  });
+
+  if (format === 'json') {
+    // Exactly one JSON object on stdout, so `| jq` / `tail -1` works.
+    process.stdout.write(resultLine(result) + '\n');
+  } else if (format === 'stream-json') {
+    // A terminating event tells a streaming reader the run is over and carries
+    // the same envelope, so both formats end with a `result` record.
+    process.stdout.write(resultLine(result) + '\n');
+  } else {
+    process.stdout.write('\n');
+  }
+  return exitCodeFor(result, false);
 }
 
 // ---- TUI dispatch ----
@@ -286,17 +356,55 @@ export async function main(argv) {
     await loadPlugins(cfg.pluginDir);
   }
 
-  // headless prompt
+  // Connect configured MCP servers and register their tools.
+  //
+  // This is a FUNCTION rather than an inline block because the two modes want
+  // different timing:
+  //   * headless (`-p`) MUST wait — the prompt runs immediately and its model
+  //     request has to see the MCP tools in the tool list.
+  //   * the TUI must NOT wait — connecting can take seconds (8s per wedged
+  //     server), and blocking the first paint for that is unacceptable. The TUI
+  //     starts this in the background and reports the result as a notice.
+  // Failures are reported but never fatal: an unreachable server must not stop
+  // the session from starting.
+  const connectMcp = async () => {
+    if (cfg.mcp === false) return { servers: [], toolCount: 0 };
+    try {
+      const mcp = await import('./mcp.js');
+      const { API } = await import('./plugin.js');
+      const mcpCfg = mcp.loadMcpConfig(cfg.workspace);
+      if (!Object.keys(mcpCfg.servers).length) return { servers: [], toolCount: 0 };
+      const res = await mcp.connectAll(mcpCfg, (spec) => API.registerTool(spec));
+      mcp.setLiveConnections(res.servers);
+      if (process.env.HNCODE_MCP_VERBOSE === '1') {
+        for (const s of res.servers) {
+          console.error(s.ok ? `[hncode-mcp] ${s.name}: ${s.toolCount} tool(s)` : `[hncode-mcp] ${s.name}: ${s.error}`);
+        }
+      }
+      return res;
+    } catch (e) {
+      console.error(`hncode: MCP setup failed: ${e.message}`);
+      return { servers: [], toolCount: 0 };
+    }
+  };
+
+  // headless prompt: MCP must be live BEFORE the request goes out.
   if (args.prompt) {
+    const format = args['output-format'];
+    if (!isValidFormat(format)) {
+      console.error(`hncode: unknown --output-format "${format}". Use one of: ${FORMATS.join(', ')}.`);
+      return EXIT.CONFIG;
+    }
+    await connectMcp();
     let session = null;
     if (args.session) session = typeof args.session === 'string' ? sess.loadSession(args.session) : sess.latestSession(undefined, undefined, { skipEmpty: true });
     else if (args.continue) session = sess.latestSession(undefined, undefined, { skipEmpty: true });
-    return runPrompt({ cfg, prompt: args.prompt, format: args['output-format'], session, modelArg: args.model });
+    return runPrompt({ cfg, prompt: args.prompt, format, session, modelArg: args.model });
   }
 
   if (!process.stdout.isTTY) {
     console.error('hncode: interactive mode requires a TTY. Use `hncode -p "prompt"` for non-interactive use.');
-    return 1;
+    return EXIT.FAILURE;
   }
 
   const opts = {
@@ -308,10 +416,16 @@ export async function main(argv) {
     auto: !!args.auto,
     plan: !!args.plan,
     addDirs: args['add-dir'] || [],
+    // Remote control: expose a local socket so a script can queue a prompt or
+    // query status on the running session (see ci.js).
+    control: args.control === true ? '' : (typeof args.control === 'string' ? args.control : null),
+    // MCP runs in the BACKGROUND once the TUI is up (see startTUI): connecting
+    // can take seconds and must not delay the first paint.
+    mcpConnect: connectMcp,
     session: loadOrCreateSession(args, cfg),
   };
   await startTui(opts);
-  return 0;
+  return EXIT.OK;
 }
 
 // main() is invoked by bin/hncode (the CLI entry point), which imports this module

package/src/llm.js

@@ -9,6 +9,7 @@
 
 import { llmTools } from './tools/index.js';
 import { effortWire } from './config.js';
+import { applyPromptCache } from './cache.js';
 
 export function openAiToolDefs(tools) {
   return tools.map((t) => ({
@@ -101,9 +102,20 @@ function buildBody(cfg, messages, streaming = true) {
   const wire = effortWire(cfg, cfg.effort) || {};
   if (cfg.protocol === 'anthropic') {
     const { system, messages: am } = toAnthropic(messages);
-    return JSON.stringify({ model: cfg.innerModel, system, messages: am, tools: anthropicToolDefs(llmToolsList), ...common, ...wire });
+    const body = { model: cfg.innerModel, system, messages: am, tools: anthropicToolDefs(llmToolsList), ...common, ...wire };
+    // Prompt caching: mark the stable prefix (tools + system + conversation head)
+    // so the provider bills it as a cache READ instead of fresh input. The key is
+    // the SESSION id, so it stays identical across turns and never thrashes.
+    return JSON.stringify(applyPromptCache('anthropic', body, {
+      enabled: cfg.promptCache !== false,
+      sessionKey: cfg.sessionId,
+    }));
   }
-  return JSON.stringify({ model: cfg.innerModel, messages: toOpenAi(messages), tools: openAiToolDefs(llmToolsList), ...common, ...wire });
+  const body = { model: cfg.innerModel, messages: toOpenAi(messages), tools: openAiToolDefs(llmToolsList), ...common, ...wire };
+  return JSON.stringify(applyPromptCache('openai', body, {
+    enabled: cfg.promptCache !== false,
+    sessionKey: cfg.sessionId,
+  }));
 }
 
 // tool list used for defs (injected via setTools)