@inetafrica/open-claudia 2.7.5 → 2.7.6

package/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## v2.7.6
+- **/tooltrace now shows WHAT ran, not just THAT it ran.** The 🔧 line per tool run was `Ran tool: kticket` — no verb, no args, and one line per tool even when different verbs ran in the same turn. It now renders the **sanitized command shape** (quoted strings → `<text>`, ids/uuids → `<id>`, paths → `<path>` — same shaping the tool graph already computes, so this is display-only and free) plus a **human-readable doc sentence for that verb**: new `tools.verbDoc(name, verb)` parses the sentence mechanically from the tool's own leading comment block (the same docs `--help` prints — zero model cost, can't drift from the source). Both documented header shapes are recognised (indented description under the verb line, or same-line prose after 2+ spaces), with fallback to the tool description's first clause. Example: `🔧 kticket show <id> — One ticket in full`. Dedup is now per tool+verb per turn, so `kticket list` then `kticket show` both announce. Unit coverage in `test-tools.js` (both shapes, sentence cut, fallback, flag-token and unknown-tool cases).
+
 ## v2.7.5
 - **Tool composition with inherited approval — a composing tool cannot self-approve (Phase 4).** Higher-order tools may shell into lower tools (report → kticket + kchat), but the callee's risk gate stays intact: `tool run` now exports the tier the **outermost** invocation's flags acknowledged (`OPEN_CLAUDIA_APPROVED_TIER`) plus the call chain (`OPEN_CLAUDIA_TOOL_STACK`) into the child env, and a nested run gates on that inherited tier while **ignoring its own argv flags** — so a composing tool that hardcodes `--yes-destructive` in its source is refused with a message pointing at the outer re-run. An inherited tier passes through unchanged (depth-safe), a tool already in the chain is refused (cycle guard), and each nested run still stamps its own telemetry. Verified live: fabricated approval blocked at exit 3, legit outer `--yes-destructive` flowing through, self-call cycle caught at depth 1.
 - **`_lib/` shared plumbing with dependent journaling (Phase 4).** Genuinely shared code (central auth, mongo-exec) now lives in `tools/_lib` — tiny modules tools import via a literal `_lib/<name>` path, never tools themselves (the registry, surfacing index, and legacy migration all skip the `_` prefix). New `tool lib list|show|set`: `set` writes the module (secret-blocking, traversal-safe), finds every dependent by a boundary-safe source grep (`central-auth` matches `_lib/central-auth.js` and the `path.join` form, **not** `central-auth-v2`), journals each dependent `unverified since _lib change — re-verified by next real use`, and commits the lot in ONE commit naming the dependents — the PLAN's blast-radius rule, since a lib change can break several tools at once and health is verified by use, not smoke tests.

package/core/runner.js

@@ -988,9 +988,14 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
       try {
         for (const run of require("./tool-graph").parseToolRuns(cmd)) {
           toolRunsThisTurn.push(run);
-          // Visibility (gated by /tooltrace): one 🔧 line per distinct tool run
-          // this turn. Telemetry (recordRun) fires at end-of-turn on success.
-          notifyToolTrace(`ran:${run.name}`, `🔧 Ran tool: ${run.name}`);
+          // Visibility (gated by /tooltrace): one 🔧 line per distinct
+          // tool+verb this turn — sanitized command shape plus the verb's own
+          // doc sentence (verbDoc: parsed mechanically from the tool header,
+          // zero model cost). Telemetry (recordRun) fires at end-of-turn.
+          const verb = (String(run.shape || "").split(/\s+/)[1] || "");
+          let doc = "";
+          try { doc = toolsLib.verbDoc(run.name, verb); } catch (e) {}
+          notifyToolTrace(`ran:${run.name}:${verb}`, `🔧 ${run.shape || run.name}${doc ? ` — ${doc}` : ""}`);
         }
       } catch (e) { /* graph optional (old node) */ }
       // `open-claudia tool add <src> [--name X]` — a tool being saved/updated.

package/core/tools.js

@@ -270,6 +270,70 @@ function parseHeader(content) {
   return out.name ? out : null;
 }
 
+// First readable clause of a doc string: cut at sentence end or " — ",
+// collapse whitespace, cap length. Used for one-line verb docs in chat.
+function firstClause(s) {
+  let t = String(s || "").replace(/\s+/g, " ").trim();
+  if (!t) return "";
+  const m = t.match(/^(.{10,}?[.!?])(?:\s|$)/);
+  if (m) t = m[1].replace(/[.!?]+$/, "");
+  else t = t.split(" — ")[0];
+  if (t.length > 90) t = t.slice(0, 87).trimEnd() + "…";
+  return t;
+}
+
+// One human-readable sentence for a tool verb, parsed mechanically from the
+// tool's own leading comment block (the same docs --help prints) — zero model
+// cost, always in sync with the source. Two documented shapes are recognised:
+//   //   kticket list [--stage a,b]        ← verb line; description on the
+//   //       List tickets. --q matches …      deeper-indented line(s) below
+//   //   inet-central users [regex]     list users; same-line prose after 2+ spaces
+// Falls back to the tool description's first clause; "" when the tool is unknown.
+function verbDoc(name, verb) {
+  let content;
+  try { content = fs.readFileSync(toolPaths(name).exec, "utf-8"); } catch (e) { return ""; }
+  const header = parseHeader(content);
+  if (!header) return "";
+  const fallback = firstClause(header.description);
+  const v = String(verb || "").trim();
+  if (!v || v.startsWith("-") || v.startsWith("<")) return fallback;
+  // Re-walk the leading comment block (same bounds as parseHeader).
+  const lines = String(content).split("\n");
+  const block = [];
+  let started = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (i === 0 && lines[i].startsWith("#!")) continue;
+    const body = uncomment(lines[i]);
+    if (body === null) {
+      if (started) break;
+      if (lines[i].trim() === "") continue;
+      break;
+    }
+    started = true;
+    block.push(body);
+  }
+  const vEsc = v.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const verbLine = new RegExp(`^(\\s+)\\S+\\s+${vEsc}\\b(.*)$`);
+  for (let i = 0; i < block.length; i++) {
+    const m = block[i].match(verbLine);
+    if (!m) continue;
+    const same = m[2].match(/\s{2,}([A-Za-z].*)$/);
+    if (same) return firstClause(same[1]);
+    const indent = m[1].length;
+    let desc = "";
+    for (let j = i + 1; j < block.length; j++) {
+      const ind = (block[j].match(/^\s*/) || [""])[0].length;
+      const text = block[j].trim();
+      if (!text || ind <= indent) break;
+      desc += (desc ? " " : "") + text;
+      if (/[.!?]$/.test(text)) break;
+    }
+    if (desc) return firstClause(desc);
+    break;
+  }
+  return fallback;
+}
+
 // Path of a tool's executable (legacy signature kept: several callers treat
 // "the tool file" as the thing you run/edit).
 function toolFile(name) {
@@ -848,7 +912,7 @@ function toolNameFromPath(filePath) {
 
 module.exports = {
   TOOLS_DIR, MARKER, USAGE_FILE, RISK_TIERS, LIB_DIR,
-  parseHeader, readTool, readToolDoc, toolCondition, listTools, findTool, runsSince, docDrift, addTool, removeTool, updateToolHeader,
+  parseHeader, readTool, readToolDoc, toolCondition, verbDoc, listTools, findTool, runsSince, docDrift, addTool, removeTool, updateToolHeader,
   runEnv, missingRequires, toolNameFromPath, sanitizeName, ensureDir, normalizeRisk,
   toolPaths, readState, writeState, recordRunResult, runGate, approvedTierFromArgv,
   listLib, readLib, writeLib, libDependents,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "2.7.5",
+  "version": "2.7.6",
   "description": "Your always-on AI coding assistant — Claude Code, Cursor Agent, and OpenAI Codex via Telegram or Kazee Chat",
   "main": "bot.js",
   "bin": {

package/test-tools.js

@@ -438,6 +438,34 @@ assert.ok(!cycle.ok && /cycle/i.test(cycle.message), "a tool already in the call
 const topLevel = tools.runGate({ name: "kticket", risk: "write" }, ["--yes"], {});
 assert.ok(topLevel.ok && !topLevel.nested, "no stack env → the classic argv-flag gate applies");
 
+// ── verbDoc: one mechanical sentence per verb, parsed from the header docs ──
+// Covers both documented shapes (indented-description-below and same-line
+// prose after 2+ spaces), the description fallback, and the unknown-tool "".
+const srcV = path.join(tmp, "vdoc.js");
+fs.writeFileSync(srcV, [
+  "#!/usr/bin/env node",
+  "// open-claudia-tool: vdoc",
+  "// description: Query the demo platform (demo.example) as operator — login, list things, show one thing",
+  "// risk: read-only",
+  "// usage: vdoc <verb> [args]",
+  "//",
+  "//   vdoc list [--stage a,b] [--json]",
+  "//       List things. Filters are regexes and",
+  "//       combine with AND.",
+  "//   vdoc peek [regex]      look at things; optional case-insensitive filter",
+  "//   vdoc stages",
+  "console.log('hi');",
+].join("\n"));
+tools.addTool(srcV, { name: "vdoc" });
+assert.strictEqual(tools.verbDoc("vdoc", "list"), "List things", "indented description below the verb line, cut at first sentence");
+assert.strictEqual(tools.verbDoc("vdoc", "peek"), "look at things; optional case-insensitive filter", "same-line prose after 2+ spaces");
+assert.strictEqual(tools.verbDoc("vdoc", "stages"), "Query the demo platform (demo.example) as operator",
+  "undocumented-body verb falls back to the description's first clause");
+assert.strictEqual(tools.verbDoc("vdoc", ""), "Query the demo platform (demo.example) as operator", "no verb → description clause");
+assert.strictEqual(tools.verbDoc("vdoc", "--json"), "Query the demo platform (demo.example) as operator", "flag token is not a verb");
+assert.strictEqual(tools.verbDoc("no-such-tool", "list"), "", "unknown tool → empty string");
+tools.removeTool("vdoc");
+
 // ── remove ──
 assert.ok(tools.removeTool("hello"), "removeTool returns the removed tool");
 assert.strictEqual(tools.findTool("hello"), null, "removed tool is gone");