agent-harness-kit 0.10.1 → 0.11.0

package/.claude-plugin/marketplace.json

@@ -11,9 +11,9 @@
       "source": {
         "source": "github",
         "repo": "tuanle96/agent-harness-kit",
-        "ref": "v0.10.1"
+        "ref": "v0.11.0"
       },
-      "version": "0.10.1",
+      "version": "0.11.0",
       "description": "Solo-dev harness engineering kit — layered architecture, GC ritual, structural tests, review subagents.",
       "category": "development",
       "keywords": [

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-harness-kit",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Solo-dev harness engineering kit — layered architecture, garbage-collection ritual, structural tests, review subagents. Optimized for Claude Code 2.1+.",
   "author": {
     "name": "Tuan Le"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-harness-kit",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Solo-dev harness engineering kit for Claude Code. Layered architecture, structural tests, garbage-collection ritual, review subagents — without the enterprise overhead.",
   "type": "module",
   "bin": {

package/src/core/render-templates.mjs

@@ -288,10 +288,14 @@ function sha256(buf) {
 }
 
 // Inject a statusLine block into .claude/settings.json. Idempotent: if the
-// existing statusLine already references the kit's script, leave it; otherwise
-// set it to invoke scripts/statusline.mjs via node. Doesn't clobber a
+// existing statusLine already references the kit's script with the desired
+// padding + refreshInterval, leave it; otherwise update. Doesn't clobber a
 // user-customised type:"command" entry that points at a different command.
 //
+// padding/refreshInterval are sourced from harness.config.json#statusline
+// (with defaults) so a user can tune through one config file and the merge
+// keeps settings.json in sync.
+//
 // Returns {changed, rawContent} for the lockfile bookkeeping (mirrors the
 // mergeHooksIntoSettings contract).
 export async function mergeStatusLineIntoSettings(cwd) {
@@ -310,9 +314,31 @@ export async function mergeStatusLineIntoSettings(cwd) {
       );
     }
   }
+
+  // Read padding + refreshInterval from harness.config.json#statusline if
+  // present; otherwise V4 defaults (padding 1, refresh 2s for live updates
+  // during long-running turns).
+  let padding = 1;
+  let refreshInterval = 2;
+  const cfgPath = resolve(cwd, "harness.config.json");
+  if (existsSync(cfgPath)) {
+    try {
+      const cfg = JSON.parse(await readFile(cfgPath, "utf8"));
+      const sl = cfg?.statusline;
+      if (sl && typeof sl === "object") {
+        if (typeof sl.padding === "number" && sl.padding >= 0) padding = sl.padding;
+        if (typeof sl.refreshInterval === "number" && sl.refreshInterval >= 1) {
+          refreshInterval = sl.refreshInterval;
+        }
+      }
+    } catch { /* malformed config → use defaults */ }
+  }
+
   const desired = {
     type: "command",
     command: "node scripts/statusline.mjs",
+    padding,
+    refreshInterval,
   };
   // Preserve a user-customised entry if it already points elsewhere. We only
   // inject when statusLine is absent OR explicitly references our script.
@@ -330,7 +356,9 @@ export async function mergeStatusLineIntoSettings(cwd) {
     cur &&
     typeof cur === "object" &&
     cur.type === desired.type &&
-    cur.command === desired.command
+    cur.command === desired.command &&
+    cur.padding === desired.padding &&
+    cur.refreshInterval === desired.refreshInterval
   ) {
     return { changed: false, rawContent: Buffer.from(raw) };
   }

package/src/templates/.claude/skills/deliver-html/SKILL.md.hbs

@@ -60,6 +60,10 @@ Do **NOT** use for:
    - Converts MD → HTML (self-rolled subset: headings, lists, code blocks,
      tables, blockquotes, links, inline formatting — no npm dependency).
    - Writes `<slug>.html` at the path you pass.
+   - **Auto-opens** the file in the default browser (`open`/`xdg-open`/`start`).
+     Suppress with `--no-open`, or by setting `AHK_DISABLE_HTML_OPEN=1` /
+     `CI=true` in the environment. Open failures (missing binary, headless
+     box) never fail the deliverable.
 
 5. **Print the deliverable contract** (the script already does this — copy it
    into your response):
@@ -69,7 +73,7 @@ Do **NOT** use for:
    **File:** <path>  (<size>)
    **Template:** decision-doc | audit-report | status-report
    **Lang:** vi | en
-   **Open:** `open <slug>.html`  (macOS)  /  `xdg-open <slug>.html`  (linux)
+   **Open:** auto-opened   (or fallback hint if --no-open / CI=true)
    ```
 
 ## Output contract

package/src/templates/.claude/skills/deliver-html/SKILL.md.vi.hbs

@@ -59,6 +59,10 @@ Trigger keyword từ user (tiếng Việt / English):
    - Convert MD → HTML (self-rolled subset: heading, list, code block, table,
      blockquote, link, inline format — không cần npm dependency).
    - Ghi `<slug>.html` tại path bạn truyền.
+   - **Tự mở** file trong browser mặc định (`open`/`xdg-open`/`start`).
+     Tắt bằng `--no-open`, hoặc set `AHK_DISABLE_HTML_OPEN=1` /
+     `CI=true` trong env. Lỗi mở (thiếu binary, headless) không làm
+     fail deliverable.
 
 5. **In deliverable contract** (script tự in — bạn copy vào response):
 
@@ -67,7 +71,7 @@ Trigger keyword từ user (tiếng Việt / English):
    **File:** <path>  (<size>)
    **Template:** decision-doc | audit-report | status-report
    **Lang:** vi | en
-   **Open:** `open <slug>.html`  (macOS)  /  `xdg-open <slug>.html`  (linux)
+   **Open:** auto-opened   (hoặc fallback hint khi --no-open / CI=true)
    ```
 
 ## Output contract

package/src/templates/scripts/_lib/statusline-cache.mjs

@@ -0,0 +1,57 @@
+// statusline-cache.mjs — tiny file-based memo for statusLine segments.
+//
+// Why this exists: Claude Code re-spawns the statusLine command on every
+// refresh, so in-process memoization is useless — each invocation is a
+// fresh node process. File-based cache keyed on `session_id` (stable per
+// Claude Code session) is the documented pattern.
+//
+// The cache lives under $TMPDIR. Each key gets a separate file with mtime
+// as the freshness signal. Reads bypass the file when stale; writes are
+// best-effort (failure to write = next call recomputes, no error surfaced).
+//
+// Usage:
+//   import { cached } from "./statusline-cache.mjs";
+//   const branch = cached(
+//     { sessionId, key: "git-branch", ttlMs: 5000 },
+//     () => spawnSync("git", ["branch", "--show-current"], ...).stdout.trim(),
+//   );
+
+import { readFileSync, writeFileSync, statSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const CACHE_DIR = join(tmpdir(), "ahk-statusline");
+
+function ensureDir() {
+  try { mkdirSync(CACHE_DIR, { recursive: true }); } catch { /* exists */ }
+}
+
+function cachePath(sessionId, key) {
+  // session_id can contain anything → sanitize. No path separator survives.
+  const safeSession = String(sessionId || "no-session").replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64);
+  const safeKey = String(key).replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 32);
+  return join(CACHE_DIR, `${safeSession}-${safeKey}.cache`);
+}
+
+// Synchronous because statusline.mjs runs as a one-shot command and the
+// upstream caller blocks on its output anyway. async would add no value.
+export function cached({ sessionId, key, ttlMs }, fetchFn) {
+  ensureDir();
+  const file = cachePath(sessionId, key);
+  try {
+    const st = statSync(file);
+    if (Date.now() - st.mtimeMs < ttlMs) {
+      return readFileSync(file, "utf8");
+    }
+  } catch { /* miss */ }
+  let value;
+  try {
+    value = fetchFn();
+  } catch {
+    value = "";
+  }
+  if (value == null) value = "";
+  const s = String(value);
+  try { writeFileSync(file, s); } catch { /* best-effort */ }
+  return s;
+}

package/src/templates/scripts/statusline.mjs

@@ -1,14 +1,47 @@
 #!/usr/bin/env node
-// statusLine — single compact line into Claude Code's TUI status bar.
-// Reads stdin (Claude Code payload), augments with kit state, emits to
-// stdout. Failure mode: print nothing rather than crash.
+// statusLine — "Two-line Dashboard" (V4).
+//
+// LINE 1 — vitals (always emitted when any segment resolves):
+//   ▶ Opus│terse│⏱1h12m  main(±3) feat:health-endpoint  ▓▓▓▓░ 42% $0.83 +156/-23
+//
+// LINE 2 — alerts (only when ≥1 trigger fires; otherwise omitted):
+//   ⚠ >200K — auto-compact next msg  ⚠ ctx 84%  ⏳ 5h limit 78%, resets in 1h12m  🚫 last-block: <title>
+//
+// Payload (Claude Code v2.1.132+ schema):
+//   model.display_name, output_style.name, session_id, version,
+//   cost.{total_cost_usd, total_duration_ms, total_lines_added, total_lines_removed},
+//   context_window.{used_percentage, context_window_size, total_input_tokens},
+//   exceeds_200k_tokens, rate_limits.five_hour.{used_percentage, resets_at}
+//
+// Behaviour gates:
+//   - NO_COLOR env or non-TTY → ANSI escapes stripped, plain text only.
+//   - harness.config.json#statusline.compact = true → line 2 dropped.
+//   - harness.config.json#statusline.{lang,showLines,showRateLimit,showLastBlock}
+//     toggle individual segments. Defaults: full features, lang from
+//     claudeMd.humanLanguage.
+//
+// Caching:
+//   - Git branch / dirty count cached 5s per session_id.
+//   - feature_list.json cached 30s.
+//   - telemetry tail cached 10s.
+//   - harness.config.json cached 60s.
+//
+// Failure mode: print nothing rather than crash. The TUI never breaks
+// because of a statusline bug.
 
 import { readFileSync, existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { spawnSync } from "node:child_process";
+import { cached } from "./_lib/statusline-cache.mjs";
 
 const CWD = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const NO_COLOR =
+  process.env.NO_COLOR != null && process.env.NO_COLOR !== "" ||
+  process.env.AHK_STATUSLINE_NO_COLOR === "1";
 
+// ---------------------------------------------------------------------------
+// Tiny helpers.
+// ---------------------------------------------------------------------------
 function safeRead(rel) {
   try { return readFileSync(resolve(CWD, rel), "utf8"); }
   catch { return null; }
@@ -21,43 +54,301 @@ function safeJSON(rel) {
 function readStdinSync() {
   try { return readFileSync(0, "utf8"); } catch { return ""; }
 }
+function num(x, def = 0) {
+  return typeof x === "number" && Number.isFinite(x) ? x : def;
+}
 
-function pieces() {
-  const out = [];
-  const lock = safeJSON(".harness/installed.json");
-  if (lock?.version) out.push(`{kit-v${lock.version}}`);
-
-  const features = safeJSON("feature_list.json");
-  if (features?.features && Array.isArray(features.features)) {
-    const open = features.features.find((f) => f.passes === false);
-    out.push(open ? `feat:${open.id}` : "feat:clean");
-  }
-
-  try {
-    const br = spawnSync("git", ["branch", "--show-current"], {
-      cwd: CWD, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
-    });
-    const status = spawnSync("git", ["status", "--short"], {
-      cwd: CWD, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"],
-    });
-    if (br.status === 0 && br.stdout.trim()) {
-      const dirty = status.stdout ? status.stdout.split("\n").filter(Boolean).length : 0;
-      out.push(dirty > 0 ? `${br.stdout.trim()}(±${dirty})` : br.stdout.trim());
+// ANSI wrappers. When NO_COLOR is set, return the bare string — every caller
+// produces uncoloured output without branching.
+const RESET = NO_COLOR ? "" : "\x1b[0m";
+function c(code, s) {
+  if (NO_COLOR || !s) return s ?? "";
+  return `\x1b[${code}m${s}${RESET}`;
+}
+const cyan    = (s) => c("36", s);
+const green   = (s) => c("32", s);
+const yellow  = (s) => c("33", s);
+const red     = (s) => c("31", s);
+const magenta = (s) => c("35", s);
+const dim     = (s) => c("2", s);
+const dimGreen = (s) => c("2;32", s);
+const dimRed   = (s) => c("2;31", s);
+
+// Color the context bar gradient by percentage band.
+function ctxColor(pct) {
+  if (pct >= 80) return red;
+  if (pct >= 50) return yellow;
+  return cyan;
+}
+
+// Color the cost by tier — under $1 dim, $1–5 default, $5+ yellow.
+function costStr(usd) {
+  const v = num(usd, 0);
+  const str = "$" + (v < 1 ? v.toFixed(2) : v < 10 ? v.toFixed(2) : v.toFixed(1));
+  if (v < 1) return dim(str);
+  if (v < 5) return str;
+  return yellow(str);
+}
+
+// ---------------------------------------------------------------------------
+// Config & locale.
+// ---------------------------------------------------------------------------
+const DEFAULT_CONFIG = {
+  compact: false,
+  lang: null,
+  showLines: true,
+  showRateLimit: true,
+  showLastBlock: true,
+};
+
+function readConfig(sessionId) {
+  const raw = cached(
+    { sessionId, key: "config", ttlMs: 60_000 },
+    () => safeRead("harness.config.json") ?? "",
+  );
+  if (!raw) return { config: DEFAULT_CONFIG, humanLanguage: "en" };
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch { return { config: DEFAULT_CONFIG, humanLanguage: "en" }; }
+  const config = { ...DEFAULT_CONFIG, ...(parsed?.statusline ?? {}) };
+  const humanLanguage = parsed?.claudeMd?.humanLanguage || "en";
+  return { config, humanLanguage };
+}
+
+const STRINGS = {
+  en: {
+    compact_soon: " — /compact soon",
+    over_200k: ">200K — auto-compact next msg",
+    rate_resets: ", resets in ",
+    last_block: "last-block: ",
+  },
+  vi: {
+    compact_soon: " — /compact sắp tới",
+    over_200k: ">200K — sắp auto-compact",
+    rate_resets: ", reset trong ",
+    last_block: "vừa block: ",
+  },
+};
+
+function pickLang(config, humanLanguage) {
+  const lang = config.lang || humanLanguage;
+  return STRINGS[lang] ? lang : "en";
+}
+
+// ---------------------------------------------------------------------------
+// Segment data fetchers (cached).
+// ---------------------------------------------------------------------------
+function fetchGit(sessionId) {
+  const raw = cached(
+    { sessionId, key: "git", ttlMs: 5_000 },
+    () => {
+      const br = spawnSync("git", ["branch", "--show-current"], {
+        cwd: CWD, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 500,
+      });
+      if (br.status !== 0 || !br.stdout) return "";
+      const branch = br.stdout.trim();
+      if (!branch) return "";
+      const st = spawnSync("git", ["status", "--short"], {
+        cwd: CWD, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 500,
+      });
+      const dirty = st.stdout ? st.stdout.split("\n").filter(Boolean).length : 0;
+      // Conflict marker check — short and cheap on already-fetched output.
+      const conflict = /^(UU|AA|DD)/m.test(st.stdout || "");
+      return JSON.stringify({ branch, dirty, conflict });
+    },
+  );
+  if (!raw) return null;
+  try { return JSON.parse(raw); } catch { return null; }
+}
+
+function fetchFeature(sessionId) {
+  const raw = cached(
+    { sessionId, key: "feat", ttlMs: 30_000 },
+    () => safeRead("feature_list.json") ?? "",
+  );
+  if (!raw) return null;
+  let features;
+  try { features = JSON.parse(raw); } catch { return null; }
+  if (!features?.features || !Array.isArray(features.features)) return null;
+  const open = features.features.find((f) => f.passes === false);
+  return { open: open?.id ?? null, clean: !open };
+}
+
+// Returns the most recent Notification record from .harness/telemetry.jsonl
+// (the file notify-on-block.sh writes a record to on every Notification
+// hook firing). Returns {ts, title} if found within the last 5 min, else
+// null. Caching avoids re-reading the JSONL on every refresh.
+function fetchLastBlock(sessionId) {
+  const raw = cached(
+    { sessionId, key: "tele", ttlMs: 10_000 },
+    () => {
+      const body = safeRead(".harness/telemetry.jsonl");
+      if (!body) return "";
+      const lines = body.split("\n").filter(Boolean);
+      for (let i = lines.length - 1; i >= 0 && i >= lines.length - 50; i--) {
+        try {
+          const rec = JSON.parse(lines[i]);
+          if (rec.hook === "Notification") {
+            return JSON.stringify({ ts: rec.ts, title: rec.title || rec.body || "" });
+          }
+        } catch { /* skip malformed */ }
+      }
+      return "";
+    },
+  );
+  if (!raw) return null;
+  let rec;
+  try { rec = JSON.parse(raw); } catch { return null; }
+  if (!rec?.ts) return null;
+  const ageMs = Date.now() - new Date(rec.ts).getTime();
+  if (!Number.isFinite(ageMs) || ageMs < 0 || ageMs > 5 * 60_000) return null;
+  return rec;
+}
+
+// ---------------------------------------------------------------------------
+// Format helpers.
+// ---------------------------------------------------------------------------
+function fmtDuration(ms) {
+  const s = Math.floor(num(ms, 0) / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  const rm = m % 60;
+  return `${h}h${String(rm).padStart(2, "0")}m`;
+}
+
+function fmtCountdown(epochSeconds) {
+  const target = Number(epochSeconds) * 1000;
+  if (!Number.isFinite(target)) return "?";
+  const ms = target - Date.now();
+  if (ms <= 0) return "0m";
+  const m = Math.floor(ms / 60_000);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  const rm = m % 60;
+  return `${h}h${String(rm).padStart(2, "0")}m`;
+}
+
+function bar(pct, width = 10) {
+  const p = Math.max(0, Math.min(100, num(pct, 0)));
+  const filled = Math.round((p / 100) * width);
+  return "▓".repeat(filled) + "░".repeat(width - filled);
+}
+
+// ---------------------------------------------------------------------------
+// Line 1 — vitals.
+// ---------------------------------------------------------------------------
+function renderLine1(payload, git, feat, config) {
+  const left = []; // identity group: model, style, duration
+  const mid = [];  // workspace group: branch, feat
+  const right = []; // burn group: ctx, cost, lines
+
+  const modelName = payload?.model?.display_name;
+  if (modelName) left.push(cyan(`▶ ${modelName}`));
+
+  const styleName = payload?.output_style?.name;
+  if (styleName && styleName !== "default") left.push(dim(styleName));
+
+  const durMs = payload?.cost?.total_duration_ms;
+  if (durMs && durMs >= 1000) left.push(dim(`⏱${fmtDuration(durMs)}`));
+
+  if (git?.branch) {
+    const tag = git.conflict ? red(`${git.branch}!CONFLICT`)
+              : git.dirty > 0 ? yellow(`${git.branch}(±${git.dirty})`)
+              : green(git.branch);
+    mid.push(tag);
+  }
+
+  if (feat) {
+    mid.push(feat.open ? magenta(`feat:${feat.open}`) : dimGreen("feat:clean"));
+  }
+
+  const pct = payload?.context_window?.used_percentage;
+  if (typeof pct === "number") {
+    const col = ctxColor(pct);
+    right.push(`${col(bar(pct))} ${col(`${Math.round(pct)}%`)}`);
+  }
+
+  const cost = payload?.cost?.total_cost_usd;
+  if (typeof cost === "number" && cost > 0) {
+    right.push(costStr(cost));
+  }
+
+  if (config.showLines) {
+    const add = num(payload?.cost?.total_lines_added, 0);
+    const rem = num(payload?.cost?.total_lines_removed, 0);
+    if (add > 0 || rem > 0) {
+      right.push(`${green("+" + add)}/${dimRed("-" + rem)}`);
     }
-  } catch { /* git not on PATH — skip */ }
+  }
 
-  const raw = readStdinSync();
-  let payload = null;
-  if (raw) { try { payload = JSON.parse(raw); } catch { /* ignore */ } }
-  if (payload?.context && typeof payload.context.percentage === "number") {
-    out.push(`ctx:${Math.round(payload.context.percentage)}%`);
+  const parts = [];
+  if (left.length) parts.push(left.join(dim("│")));
+  if (mid.length) parts.push(mid.join("  "));
+  if (right.length) parts.push(right.join(" "));
+  return parts.join("  ");
+}
+
+// ---------------------------------------------------------------------------
+// Line 2 — alerts.
+// ---------------------------------------------------------------------------
+function renderLine2(payload, sessionId, config, lang) {
+  if (config.compact) return "";
+  const t = STRINGS[lang];
+  const alerts = [];
+
+  // Order by severity: hardest stop first.
+  if (payload?.exceeds_200k_tokens === true) {
+    alerts.push(red(`⚠ ${t.over_200k}`));
   }
-  if (payload?.cost && typeof payload.cost.total === "number") {
-    const v = payload.cost.total;
-    out.push(`$${v < 1 ? v.toFixed(2) : v.toFixed(1)}`);
+
+  const pct = payload?.context_window?.used_percentage;
+  if (typeof pct === "number" && pct >= 80 && payload?.exceeds_200k_tokens !== true) {
+    alerts.push(red(`⚠ ctx ${Math.round(pct)}%${t.compact_soon}`));
   }
-  return out;
+
+  if (config.showRateLimit) {
+    const five = payload?.rate_limits?.five_hour;
+    if (five && typeof five.used_percentage === "number" && five.used_percentage >= 75) {
+      const resetTxt = five.resets_at ? `${t.rate_resets}${fmtCountdown(five.resets_at)}` : "";
+      alerts.push(yellow(`⏳ 5h limit ${Math.round(five.used_percentage)}%${resetTxt}`));
+    }
+  }
+
+  if (config.showLastBlock) {
+    const lb = fetchLastBlock(sessionId);
+    if (lb) {
+      const title = String(lb.title || "").slice(0, 40);
+      alerts.push(red(`🚫 ${t.last_block}${title}`));
+    }
+  }
+
+  return alerts.join("  ");
+}
+
+// ---------------------------------------------------------------------------
+// Main.
+// ---------------------------------------------------------------------------
+function main() {
+  const raw = readStdinSync();
+  let payload = {};
+  if (raw) {
+    try { payload = JSON.parse(raw) || {}; } catch { payload = {}; }
+  }
+  const sessionId = payload?.session_id || "no-session";
+  const { config, humanLanguage } = readConfig(sessionId);
+  const lang = pickLang(config, humanLanguage);
+
+  const git = fetchGit(sessionId);
+  const feat = fetchFeature(sessionId);
+
+  const line1 = renderLine1(payload, git, feat, config);
+  const line2 = renderLine2(payload, sessionId, config, lang);
+
+  const out = [];
+  if (line1) out.push(line1);
+  if (line2) out.push(line2);
+  if (out.length) process.stdout.write(out.join("\n"));
 }
 
-const line = pieces().join(" • ");
-if (line) process.stdout.write(line);
+try { main(); } catch { /* swallow — never crash the TUI */ }