@inetafrica/open-claudia 2.7.2 → 2.7.3

package/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## v2.7.3
+- **Surfaced tools now carry their condition (tiered surfacing, Phase 2/item 6).** The per-turn "Tools that may help here" block rendered one identity line per tool — name, description, keyring needs — so the agent knew a tool *existed* but not what state it was in, and had to spend a `tool show` (or just run it blind) to find out it was broken, never proven, or failing since Tuesday. Each surfaced tool is now a **2-line headline**: line 1 is identity (name — description, risk tier, keyring needs, why it surfaced), line 2 is condition — the TOOL.md **State** headline (first line, truncated), the open **known-issue count** (⚠ n), and **last-run health** from telemetry (`last run OK/FAILED (exit n) <date>, n runs`, or `never run`; legacy flat tools without exit telemetry degrade to `last used`). This completes the tiering ladder: 2-line headline always → TOOL.md via `tool show` → source only via `--source` — you read the manual, not the disassembly, and now the cover tells you if the manual has errata. New `tools.toolCondition()` with unit coverage in `test-tools.js` (headline extraction, `(none yet)` filtering, health formats, clean degrade) and end-to-end render assertions in `test-recall-discoverer.js`.
+
 ## v2.7.2
 - **Credential confinement — keyring creds now live ONLY inside tool runs (enforcement 5b).** Until now `botSubprocessEnv()` merged the whole operational keyring into *every* agent subprocess, so the agent's own Bash (and any sub-agent) could `curl` a prod API with `$inet_central_user` directly — the tool layer was optional. That merge is gone: agent shells and sub-agents run cred-free, and `tools.runEnv(tool)` injects **only the keys a tool declares via `--requires`**, read fresh from the keyring at run time (least privilege; `process.env` still wins on conflict). Audited all 11 live tools before shipping: every keyring key read is already declared, so nothing breaks. The system prompt's Preauth bullet now tells the truth, and `keyring list` no longer claims env-wide availability.
 - **Tool-first deny-gate on the agent's shell (enforcement 5b).** A PreToolUse hook (wired via `--settings` into the main runner *and* sub-agent spawns; new `core/tool-guard.js` + `open-claudia deny-gate-hook`) blocks raw operational commands against known prod surfaces and redirects to the covering tool by name — or to the exact `tool scaffold` command when nothing covers the surface yet. v1 rules are deliberately high-precision: an **acting** binary (curl/wget/ssh/mongosh/…) aimed at `central.inet.africa`, `ticketcentral`, `10.200.0.0/16`, `kubectl exec … mongo(sh)`, or `ssh codersafrica@` — while `grep`/`cat`/`ping` mentioning the same surfaces, read-only `kubectl`, and plain `git push` stay free (reading is always allowed; acting goes through tools). Quotes count as command separators so `bash -c "curl …"` can't dodge the gate. Every failure mode in the gate fails OPEN — a broken guard must never brick the shell. This gate is the honest enforcement for surfaces where confinement is toothless (kubectl/ssh use ambient creds, not keyring keys); the accepted residual dodge is writing the command into a script file first.

package/core/recall/discoverer.js

@@ -515,12 +515,21 @@ async function run(ctx) {
   }
   let toolBlock = "";
   if (toolMatches.length) {
+    // Tiered injection (Phase 2): a 2-line headline per tool — identity line
+    // (name, description, risk tier, keyring needs, why surfaced) plus a
+    // condition line (TOOL.md State headline, open issues, last-run health) so
+    // the agent knows the tool's shape AND state without loading the manual.
     const lines = toolMatches.map((m) => {
       const t = toolsLib.findTool(m.name);
-      const needs = t && t.requires && t.requires.length ? ` (keyring: ${t.requires.join(", ")})` : "";
-      return `- ${m.name} — ${m.description || "(no description)"}${needs}${m.why ? ` — ${m.why}` : ""}`;
+      const meta = [];
+      if (t && t.risk) meta.push(t.risk);
+      if (t && t.requires && t.requires.length) meta.push(`keyring: ${t.requires.join(", ")}`);
+      const head = `- ${m.name} — ${m.description || "(no description)"}${meta.length ? ` (${meta.join("; ")})` : ""}${m.why ? ` — ${m.why}` : ""}`;
+      let cond = "";
+      try { cond = toolsLib.toolCondition(t); } catch (e) {}
+      return cond ? `${head}\n  ↳ ${cond}` : head;
     });
-    toolBlock = `\n\n## Tools that may help here\nSurfaced for this turn — run with \`open-claudia tool run <name> [args]\`; read docs/source with \`open-claudia tool show <name>\`:\n${lines.join("\n")}\n`;
+    toolBlock = `\n\n## Tools that may help here\nSurfaced for this turn — read the manual with \`open-claudia tool show <name>\`, then run with \`open-claudia tool run <name> [args]\`:\n${lines.join("\n")}\n`;
   }
 
   // 5a tool-scout: replace the silence of an empty/partial tool match with an

package/core/tools.js

@@ -316,6 +316,40 @@ function readToolDoc(name) {
   try { return fs.readFileSync(p.doc, "utf-8"); } catch (e) { return ""; }
 }
 
+function sectionOf(doc, heading) {
+  const m = String(doc || "").match(new RegExp(`##\\s*${heading}[^\\n]*\\n([\\s\\S]*?)(?=\\n##\\s|$)`, "i"));
+  return m ? m[1] : "";
+}
+
+// One-line condition digest for the per-turn surfacing block (tiered injection:
+// headline always → TOOL.md via `tool show` → source only via --source). Rides
+// under the tool's headline so the agent knows its condition BEFORE running it:
+// TOOL.md's State headline, open known-issue count, last-run health from
+// telemetry. "" when there is nothing worth saying.
+function toolCondition(t) {
+  if (!t || !t.name) return "";
+  const parts = [];
+  const doc = readToolDoc(t.name);
+  if (doc) {
+    const headline = sectionOf(doc, "State").split("\n")
+      .map((l) => l.trim())
+      .find((l) => l && !/^\(none/i.test(l) && !l.startsWith("#"));
+    if (headline) parts.push(headline.length > 120 ? `${headline.slice(0, 117)}…` : headline);
+    const issues = sectionOf(doc, "Known issues").split("\n").filter((l) => /^\s*-\s*\S/.test(l)).length;
+    if (issues) parts.push(`⚠ ${issues} known issue${issues === 1 ? "" : "s"}`);
+  }
+  if (!t.runCount) parts.push("never run");
+  else {
+    const when = (t.lastUsed || "").slice(0, 10);
+    // Legacy flat tools have no lastExit — usage count is all we can say.
+    const health = typeof t.lastExit === "number"
+      ? (t.lastExit === 0 ? "last run OK" : `last run FAILED (exit ${t.lastExit})`)
+      : "last used";
+    parts.push(`${health}${when ? ` ${when}` : ""}, ${t.runCount} run${t.runCount === 1 ? "" : "s"}`);
+  }
+  return parts.join(" · ");
+}
+
 function listTools() {
   let entries;
   try { entries = fs.readdirSync(TOOLS_DIR); } catch (e) { return []; }
@@ -678,7 +712,7 @@ function toolNameFromPath(filePath) {
 
 module.exports = {
   TOOLS_DIR, MARKER, USAGE_FILE, RISK_TIERS,
-  parseHeader, readTool, readToolDoc, listTools, findTool, addTool, removeTool, updateToolHeader,
+  parseHeader, readTool, readToolDoc, toolCondition, listTools, findTool, addTool, removeTool, updateToolHeader,
   runEnv, missingRequires, toolNameFromPath, sanitizeName, ensureDir, normalizeRisk,
   toolPaths, readState, writeState, recordRunResult, runGate,
   matchTools, recordRun, recordCreate, readUsage,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "2.7.2",
+  "version": "2.7.3",
   "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-recall-discoverer.js

@@ -26,6 +26,16 @@ toolsLib.addTool((() => {
   fs.writeFileSync(s, "#!/usr/bin/env bash\necho audit\n");
   return s;
 })(), { name: "mikrotik-audit", description: "audit the mikrotik router fleet inventory" });
+// Give the fixture a condition (Phase 2 tiered surfacing): TOOL.md State
+// headline + a known issue + failed-run telemetry, so the 2-line headline can
+// be asserted end-to-end through the renderer.
+fs.writeFileSync(path.join(process.env.TOOLS_DIR, "mikrotik-audit", "TOOL.md"), [
+  "# mikrotik-audit", "", "## Interface", "audit the mikrotik router fleet inventory", "",
+  "## Known issues", "- [2026-07-01] R2 times out on list", "",
+  "## State", "Covers 12 routers; R2 flaky.", "",
+  "## Journal", "- [2026-07-01] Created.", "",
+].join("\n"));
+toolsLib.writeState("mikrotik-audit", { createdAt: "2026-07-01T00:00:00Z", lastUsed: "2026-07-01T10:00:00.000Z", runCount: 3, lastExit: 1 });
 
 // --- tiered pre-gate ---
 assert.strictEqual(disc.needsRecall("", 0), false, "empty → no recall");
@@ -114,6 +124,12 @@ const helpers = { packsLib, entitiesLib, mergeMatches, buildPackBlock, buildEnti
   assert.ok(outTool.toolMatches.some((m) => m.name === "mikrotik-audit"), "matching tool is kept (seeds-tier user seed)");
   assert.ok(/mikrotik-audit/.test(outTool.toolBlock), "kept tool renders into the toolBlock");
   assert.ok(/Tools that may help here/.test(outTool.toolBlock), "toolBlock carries its heading");
+  // Phase 2 tiered surfacing: headline line 1 carries identity (risk tier),
+  // line 2 carries condition — State headline, issue count, last-run health.
+  assert.ok(/\(write\)/.test(outTool.toolBlock), "identity line carries the risk tier");
+  assert.ok(/↳ Covers 12 routers; R2 flaky\./.test(outTool.toolBlock), "condition line leads with the TOOL.md State headline");
+  assert.ok(/⚠ 1 known issue/.test(outTool.toolBlock), "condition line counts open known issues");
+  assert.ok(/last run FAILED \(exit 1\) 2026-07-01, 3 runs/.test(outTool.toolBlock), "condition line reports last-run health");
 
   // full-tier fail-open: with no judge, an unjudged TOOL is a guess — dropped.
   // (Measured before the fix: a failed walk kept 15 unjudged seeds including

package/test-tools.js

@@ -309,6 +309,31 @@ try {
   assert.ok(fs.readFileSync(path.join(process.env.TOOLS_DIR, ".gitignore"), "utf-8").includes("state.json"), "state.json is gitignored");
 } catch (e) { console.log("  (git not available — history assertions skipped)"); }
 
+// ── toolCondition: the surfacing digest (Phase 2 tiered injection) — TOOL.md
+//    State headline + open-issue count + last-run health; degrades cleanly ──
+const condSrc = path.join(tmp, "condtool.sh");
+fs.writeFileSync(condSrc, "#!/usr/bin/env bash\necho ok\n");
+tools.addTool(condSrc, { name: "condtool", description: "probes widgets" });
+const freshCond = tools.toolCondition(tools.findTool("condtool"));
+assert.ok(/Scaffolded .* — not yet proven/.test(freshCond), "fresh tool leads with the skeleton State line");
+assert.ok(/never run/.test(freshCond), "zero runs read as never run");
+assert.ok(!/known issue/.test(freshCond), "\"(none yet)\" placeholder is not an issue");
+fs.writeFileSync(path.join(process.env.TOOLS_DIR, "condtool", "TOOL.md"), [
+  "# condtool", "", "## Interface", "probes widgets", "",
+  "## Known issues", "- [2026-07-01] list verb times out on slow links", "- [2026-07-02] json flag ignored", "",
+  "## State", "Covers 12 widget hosts; watch host-7.", "More detail that must not surface.", "",
+  "## Journal", "- [2026-07-01] Created.", "",
+].join("\n"));
+tools.writeState("condtool", { createdAt: "2026-07-01T00:00:00Z", lastUsed: "2026-07-02T10:00:00.000Z", runCount: 3, lastExit: 1 });
+const cond = tools.toolCondition(tools.findTool("condtool"));
+assert.ok(cond.startsWith("Covers 12 widget hosts; watch host-7."), "State headline (first line only) leads the digest");
+assert.ok(!/must not surface/.test(cond), "only the State headline surfaces, not the whole section");
+assert.ok(/⚠ 2 known issues/.test(cond), "open known-issue count rides along");
+assert.ok(/last run FAILED \(exit 1\) 2026-07-02, 3 runs/.test(cond), "failed last run carries exit, date, and run count");
+tools.writeState("condtool", { createdAt: "2026-07-01T00:00:00Z", lastUsed: "2026-07-03T09:00:00.000Z", runCount: 4, lastExit: 0 });
+assert.ok(/last run OK 2026-07-03, 4 runs/.test(tools.toolCondition(tools.findTool("condtool"))), "healthy last run reads OK");
+assert.strictEqual(tools.toolCondition(null), "", "no tool → empty digest");
+
 // ── remove ──
 assert.ok(tools.removeTool("hello"), "removeTool returns the removed tool");
 assert.strictEqual(tools.findTool("hello"), null, "removed tool is gone");