@inetafrica/open-claudia 2.7.0 → 2.7.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v2.7.1
+- **The system prompt now teaches tool-FIRST, not tool-after (enforcement 5d).** The fixed "Reusable tools" section in `core/system-prompt.js` was the root cause of the baseline failure: it taught "crystallise the script you just wrote" — do the work raw, save a tool afterwards. Rewritten as "Tools are the interface": before operational work, walk the loop **search → use (read TOOL.md first, never guess args) → extend the missing verb → scaffold first** — and only then do the work *through* the tool. Raw one-liners and heredocs are demoted to probing/diagnosis; a broken tool gets fixed or journaled (`tool note --issue`), never routed around. The section also documents the risk gate honestly: the `--yes`/`--yes-destructive` flag is the agent's mechanical acknowledgment *after* the user approves — it never replaces asking first.
+- **Tool-scout: operational turns can no longer meet silence (enforcement 5a).** Today an empty tool match is silent, and silence reads as permission to improvise. The discoverer now runs a pattern-based scout (no LLM, ~zero cost) over each seeds/full-tier turn: a table of high-precision operational domains — named hosts (central.inet.africa, ticket-central, chat-central, git.coders.africa…), prod IP ranges, infra commands (kubectl, argocd, mongosh…) — each with a `covers` matcher against the tool registry. When a turn trips a domain: if a registry tool covers it but wasn't auto-surfaced, the block points at it by name (`tool show X`, then work through it); if **nothing** covers it, the block says so and hands over the exact scaffold command (`tool scaffold <suggested-name> --risk write`). Domains already covered by a surfaced tool stay quiet, and non-operational chatter never trips the patterns (precision over recall — they expand from audit evidence later, per 5c). Gap signals flow into recall metrics (`toolGaps`) and the engine result for future `/tooltrace` surfacing. Extends `test-recall-discoverer.js` with pure-function and through-the-engine scout coverage.
+
 ## v2.7.0
 - **Tools become memory objects (tool-first architecture, Phase 1).** A tool is no longer a flat script — it's a directory: `tools/<name>/tool` (the executable), `TOOL.md` (Interface · Known issues · State · Journal — the curated, human-readable condition of the tool), and `state.json` (machine telemetry, runtime-written, gitignored). The tools dir is now a **git repository**: every add, metadata change, note, and removal auto-commits (with a per-invocation identity, never touching git config), so `git log` *is* the upgrade history and any change is one revert from undone. `tool show` is tiered disclosure: header metadata, live telemetry, TOOL.md, and the recent commit log — the source only with `--source`, so reading about a tool no longer costs its whole body in context.
 - **Risk tiers + run gate.** Every tool declares `risk: read-only | write | destructive` in its header (absent = treated as write, fail-safe). `tool run` now enforces the ask-first rule mechanically: read-only runs freely; write requires `--yes`; destructive requires `--yes-destructive` — and a plain `--yes` does **not** unlock a destructive tool. Refusals exit 3 with a clear message. The flags pass through to the tool unstripped, so tools with their own confirmation gates (e.g. prod-k8s) keep working. `tool add`/`tool set` accept `--risk`; adding without it defaults to write and says so.

package/core/recall/discoverer.js

@@ -27,6 +27,65 @@ const toolsLib = require("../tools");
 // entity-only). Optional — absent on old node where node:sqlite is missing.
 let toolGraph = null;
 try { toolGraph = require("../tool-graph"); } catch (e) { /* old node */ }
+
+// ── Tool-scout (enforcement 5a): operational-domain gap detection ────────────
+// When a turn looks operational, an empty tool match must not stay silent —
+// silence reads as permission to improvise a raw script. v1 is pure patterns,
+// no LLM: `test` decides the turn touches an operational domain (named hosts,
+// prod IPs, infra commands — precision over recall so local/dev chatter never
+// trips it); `covers` finds a registry tool that fronts that domain (matched
+// on name + description); `slug` is the suggested scaffold name when nothing
+// in the registry covers it. Patterns expand from audit evidence (5c).
+const OPERATIONAL_DOMAINS = [
+  { label: "Kubernetes cluster ops", test: /\bkubectl\b|\bargocd\b|control[- ]plane|\brollout (?:status|restart|history)\b/i, covers: /k8s|kubernetes|kubectl|cluster/i, slug: "prod-k8s" },
+  { label: "in-cluster MongoDB", test: /\bmongosh\b|\bmongo\b[^\n]*--eval|\bdb\.\w+\.(?:find|update\w*|delete\w*|insert\w*|aggregate)\(/i, covers: /mongo|k8s/i, slug: "prod-k8s" },
+  { label: "inet-central platform API", test: /central\.inet\.africa|\binet[- ]central\b/i, covers: /inet[- ]?central/i, slug: "inet-central-cli" },
+  { label: "ticket-central API", test: /ticketcentral|\bticket[- ]central\b/i, covers: /\bticket/i, slug: "kticket" },
+  { label: "kazee chat-central API", test: /\bchat[- ]central\b/i, covers: /kazee-chat|chat/i, slug: "kchat" },
+  { label: "kazee spaces API", test: /spaces\.kazee|\bspaces[- ]central\b/i, covers: /spaces/i, slug: "spaces" },
+  { label: "GitLab / coders.africa", test: /git\.coders\.africa|codersafrica@|\bgitlab\b/i, covers: /gitlab|coders/i, slug: "gitlab-ops" },
+  { label: "MikroTik / RouterOS", test: /mikrotik|routeros|winbox|\/rest\/(?:ip|ppp|queue)\b/i, covers: /mikrotik|routeros/i, slug: "mikrotik" },
+  { label: "iNet radius/ops backend", test: /radius\.inet\.africa|ops\.inet\.africa/i, covers: /radius|pppoe/i, slug: "inet-radius" },
+  { label: "production network host", test: /\b10\.200\.\d{1,3}\.\d{1,3}\b|\b102\.222\.4\.\d{1,3}\b/, covers: null, slug: "" },
+];
+
+// Pure + exported for tests. Returns [{ label, kind: "use", tool }] when a
+// registry tool covers a tripped domain but was not surfaced this turn, or
+// [{ label, kind: "scaffold", slug }] when nothing in the registry covers it.
+// Domains already covered by a surfaced (kept) tool produce no signal.
+function scoutToolGaps(userText, keptToolNames, allTools) {
+  const text = String(userText || "");
+  if (!text) return [];
+  let all = allTools;
+  if (!all) { try { all = toolsLib.listTools(); } catch (e) { return []; } }
+  const kept = [...(keptToolNames || [])].map((n) => String(n).toLowerCase());
+  const gaps = [];
+  const seen = new Set();
+  for (const d of OPERATIONAL_DOMAINS) {
+    if (!d.test.test(text)) continue;
+    if (d.covers && kept.some((n) => d.covers.test(n))) continue;
+    const hit = d.covers
+      ? all.find((t) => d.covers.test(t.name) || d.covers.test(String(t.description || "")))
+      : null;
+    if (hit && kept.includes(hit.name.toLowerCase())) continue;
+    const g = hit
+      ? { label: d.label, kind: "use", tool: hit.name }
+      : { label: d.label, kind: "scaffold", slug: d.slug || "" };
+    const key = g.kind + ":" + (g.tool || g.slug || g.label);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    gaps.push(g);
+  }
+  return gaps;
+}
+
+function renderToolGaps(gaps) {
+  if (!gaps || !gaps.length) return "";
+  const lines = gaps.map((g) => g.kind === "use"
+    ? `- ${g.label}: covered by existing tool \`${g.tool}\` (not auto-surfaced this turn) — \`open-claudia tool show ${g.tool}\`, then work through it.`
+    : `- ${g.label}: NO tool covers this domain. Scaffold before improvising: \`open-claudia tool scaffold ${g.slug || "<system-name>"} --desc "<what it fronts>" --risk write\` — implement the verb you need, then do the work through it.`);
+  return `\n\n## Tool-first check (operational turn)\nThis turn touches operational domains. Do the operational work THROUGH a tool — raw one-liners only to probe:\n${lines.join("\n")}\n`;
+}
 // Episodic memory: FTS over past transcripts (same optionality as the graphs).
 let transcriptIndex = null;
 try { transcriptIndex = require("../transcript-index"); } catch (e) { /* old node */ }
@@ -236,7 +295,7 @@ async function run(ctx) {
   const tier = recallTier(userText, seedCount);
   if (tier === "skip") {
     metrics.logTurn({ engine: "discoverer", model: WALKER_MODEL, query: userText, gated: true, tier, latencyMs: Date.now() - started });
-    return { packBlock: "", entityBlock: "", toolBlock: "", episodeBlock: "", packMatches: [], entityMatches: [], toolMatches: [], episodeMatches: [], why: {}, gated: true, tier };
+    return { packBlock: "", entityBlock: "", toolBlock: "", episodeBlock: "", packMatches: [], entityMatches: [], toolMatches: [], toolGaps: [], episodeMatches: [], why: {}, gated: true, tier };
   }
 
   // 3: spreading activation from seeds across the graph (full tier only — the
@@ -464,6 +523,14 @@ async function run(ctx) {
     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`;
   }
 
+  // 5a tool-scout: replace the silence of an empty/partial tool match with an
+  // explicit use-this-tool or scaffold-first signal on operational turns. Runs
+  // on both seeds and full tiers (short command-like turns are exactly the
+  // operational ones); skip-tier pleasantries never reach here.
+  let toolGaps = [];
+  try { toolGaps = scoutToolGaps(userText, toolMatches.map((m) => m.name)); } catch (e) {}
+  if (toolGaps.length) toolBlock += renderToolGaps(toolGaps);
+
   // Past-conversation episodes the walker kept (fail-open drops them — an
   // unjudged transcript snippet is a guess, not a memory).
   const episodeMatches = episodeCands
@@ -497,12 +564,13 @@ async function run(ctx) {
     walkerMs: walkRes.walkerMs,
     walker: walkRes.source,
     costUsd: walkRes.costUsd || 0,
+    toolGaps: toolGaps.length ? toolGaps.map((g) => `${g.kind}:${g.tool || g.slug || g.label}`) : undefined,
   });
 
   return {
     packBlock, entityBlock, toolBlock, episodeBlock, packMatches: finalPacks, entityMatches: finalEnts,
-    toolMatches, episodeMatches, why: whyMap ? Object.fromEntries(whyMap) : {}, gated: false, tier,
+    toolMatches, toolGaps, episodeMatches, why: whyMap ? Object.fromEntries(whyMap) : {}, gated: false, tier,
   };
 }
 
-module.exports = { name: "discoverer", run, needsRecall, recallTier, walk, cascadeVerdict };
+module.exports = { name: "discoverer", run, needsRecall, recallTier, walk, cascadeVerdict, scoutToolGaps, renderToolGaps };

package/core/system-prompt.js

@@ -79,18 +79,25 @@ function buildToolIndexBlock() {
     if (count) {
       listing = `\nYou have ${count} reusable tool${count === 1 ? "" : "s"}. The ones relevant to a turn are surfaced automatically below (\"Tools that may help here\"). To find others on demand: \`open-claudia tool search <query>\` (lexical match) or \`open-claudia tool list\`; read docs/source with \`open-claudia tool show <name>\`; run with \`open-claudia tool run <name> [args]\`.\n`;
     } else {
-      listing = "\nNo reusable tools saved yet — the first time you work out how to hit an API or drive an interface, save it as one.\n";
+      listing = "\nNo reusable tools exist yet — your first operational task starts by scaffolding the tool for it, not by improvising a script.\n";
     }
   } catch (e) {
     return "";
   }
-  return `\n## Reusable tools (build skills as you work)
-When you work out how to do something operational — hit an API, drive an interface, transform a file, run a multi-step flow — do NOT leave it as a throwaway heredoc. Crystallise it into a reusable tool so next time it's a single command, not a re-derivation. This is a core behaviour, not an optional extra: prefer saving a tool over re-typing a script you've written before.
+  return `\n## Tools are the interface (tool-first)
+Operational work — hitting an API, mutating a live system, driving an interface, any command you would re-derive next time — happens THROUGH a reusable tool, not around one. BEFORE doing the work, walk this loop in order:
 
-- A tool is one executable file (any language; shebang picks the interpreter) with a parseable comment header. Save the script you just wrote with \`open-claudia tool add <path> --pack <skill-dir> --desc "..." [--requires "key1,key2"] [--usage "..."]\`. The \`--pack\` link ties it to the matching skill pack so the prose how-to and the runnable how-to stay together.
-- Preauth: tools run with the operational keyring merged into their environment — and so does your OWN Bash, right now. Every operational credential is already present as an environment variable in your shell and in any tool you run; reference it as \`$inet_central_user\` etc. instead of asking for it or hardcoding it. Run \`open-claudia keyring list\` to see the exact names available. In a saved tool, declare what it needs via \`--requires\` so a missing key is reported before the run, and never write a secret into the file.
-- Read a tool's docs and source on demand with \`open-claudia tool show <name>\` (don't guess its args). Full CLI: \`open-claudia tool list|show|add|run|remove\`.
-- When a tool's behaviour changes or you improve it, update the saved tool rather than forking a new heredoc. Announce in one line when you create or change a tool, same as packs.
+1. **Search** — check the "Tools that may help here" block if present; otherwise \`open-claudia tool search <query>\` or \`tool list\`.
+2. **Use** — a tool covers it: read it first (\`open-claudia tool show <name>\` gives docs, State, known issues, recent changes — never guess its args; \`--source\` only when modifying), then \`open-claudia tool run <name> <verb> [args]\`.
+3. **Extend** — right tool, missing verb: add the verb to that tool (\`tool edit <name>\`, then \`tool note <name> --journal "added <verb>"\`) and run it. One CLI per system, verbs as subcommands — never fork a near-duplicate.
+4. **Scaffold** — no tool fronts the system: \`open-claudia tool scaffold <name> --desc "..." --risk <read-only|write|destructive> [--pack <dir>] [--requires "key1,key2"]\` FIRST, implement the verb you need, then do the work through it.
+
+Raw shell one-liners and heredocs are for probing and diagnosis only — never the operational action itself. If a tool is broken, fix it or journal the defect (\`tool note <name> --issue "..."\`); do not route around it with a script.
+
+- Risk gate: read-only tools run freely; write-tier needs \`--yes\`; destructive needs \`--yes-destructive\`. The flag is your mechanical acknowledgment AFTER the user approves the action — it never replaces asking first.
+- Tools carry their own memory: TOOL.md (Interface · Known issues · State · Journal) is the manual, state.json records every run (per-verb health), and every change is a git commit. Keep TOOL.md truthful as you work; update the tool in place when behaviour changes.
+- Preauth: the operational keyring is merged into tool runs — and into your own Bash. Reference creds as \`$inet_central_user\` etc. (\`open-claudia keyring list\` shows names); declare a tool's needs via \`--requires\` so a missing key reports before the run; never write a secret into a tool file (saves are refused).
+- Announce in one line when you scaffold or change a tool, same as packs. Full CLI: \`open-claudia tool list|search|show|scaffold|add|set|note|edit|run|migrate|remove\`.
 ${listing}`;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "2.7.0",
+  "version": "2.7.1",
   "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

@@ -124,7 +124,12 @@ const helpers = { packsLib, entitiesLib, mergeMatches, buildPackBlock, buildEnti
   });
   assert.strictEqual(outToolFull.tier, "full", "substantive ask lands on the full tier");
   assert.strictEqual(outToolFull.toolMatches.length, 0, "fail-open drops unjudged tools at full tier");
-  assert.strictEqual(outToolFull.toolBlock, "", "no unjudged toolBlock at full tier");
+  // 5a: the drop no longer leaves silence — the turn is operational (mikrotik),
+  // so the scout points at the covering tool by name instead of injecting it
+  // unjudged. No "Tools that may help here" injection, but a Tool-first check.
+  assert.ok(!/Tools that may help here/.test(outToolFull.toolBlock), "no unjudged tool injection at full tier");
+  assert.ok(/Tool-first check/.test(outToolFull.toolBlock), "scout replaces fail-open silence on an operational turn");
+  assert.ok(/mikrotik-audit/.test(outToolFull.toolBlock), "scout names the covering tool");
 
   const outNoTool = await disc.run({
     userText: "help with the mobile app", contextText: "", fullContext: "help with the mobile app",
@@ -133,6 +138,36 @@ const helpers = { packsLib, entitiesLib, mergeMatches, buildPackBlock, buildEnti
   assert.strictEqual(outNoTool.toolBlock, "", "no tool match → empty toolBlock");
   assert.strictEqual(outNoTool.toolMatches.length, 0, "no tool match → no toolMatches");
 
+  // --- 5a tool-scout: operational-domain gap detection (pure function) ---
+  const reg = [{ name: "prod-k8s", description: "Production k8s cluster ops" }];
+  let gaps = disc.scoutToolGaps("check the pods with kubectl on prod", [], reg);
+  assert.deepStrictEqual(gaps, [{ label: "Kubernetes cluster ops", kind: "use", tool: "prod-k8s" }],
+    "operational turn + registry tool not surfaced → use signal");
+  gaps = disc.scoutToolGaps("check the pods with kubectl on prod", ["prod-k8s"], reg);
+  assert.deepStrictEqual(gaps, [], "kept tool covering the domain → no signal");
+  gaps = disc.scoutToolGaps("run kubectl and a mongosh eval on the cluster", [], reg);
+  assert.strictEqual(gaps.length, 1, "two domains covered by one tool dedupe to one signal");
+  gaps = disc.scoutToolGaps("pull the open tickets from ticket-central", [], reg);
+  assert.deepStrictEqual(gaps, [{ label: "ticket-central API", kind: "scaffold", slug: "kticket" }],
+    "operational turn + nothing in registry → scaffold-first signal with suggested name");
+  gaps = disc.scoutToolGaps("what should we cook for dinner tonight", [], reg);
+  assert.deepStrictEqual(gaps, [], "non-operational turn → scout stays silent");
+  assert.strictEqual(disc.renderToolGaps([]), "", "no gaps → no block");
+  assert.ok(/tool scaffold kticket/.test(disc.renderToolGaps([{ label: "ticket-central API", kind: "scaffold", slug: "kticket" }])),
+    "scaffold signal carries the exact command");
+
+  // scout through the engine: an operational turn with no covering tool in the
+  // fixture registry renders the Tool-first check even though toolMatches is empty
+  const outGap = await disc.run({
+    userText: "pull the open tickets from the ticket-central api", contextText: "",
+    fullContext: "pull the open tickets from the ticket-central api", packLimit: 6, budget: {}, helpers,
+  });
+  assert.strictEqual(outGap.toolMatches.length, 0, "no tool matches the ticket domain");
+  assert.ok(/Tool-first check/.test(outGap.toolBlock), "gap block renders on an operational turn");
+  assert.ok(/tool scaffold kticket/.test(outGap.toolBlock), "gap block carries the scaffold command");
+  assert.ok(Array.isArray(outGap.toolGaps) && outGap.toolGaps[0].kind === "scaffold", "toolGaps returned in the result");
+  assert.deepStrictEqual(gated.toolGaps, [], "gated turn returns empty toolGaps");
+
   // seeds tier: a short command-like turn skips graph+walker but still injects
   // keyword seeds directly (classic baseline, ~ms path).
   builtPacks = null;