@inetafrica/open-claudia 2.6.48 → 2.6.50

package/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## v2.6.49
+- **Reusable tools + a directed tool-usage graph.** Two linked features. First, **reusable tools** (`core/tools.js`, `bin/tool.js`): the executable sibling of context packs — when the agent works out an operational procedure (hit an API, drive an interface, transform a file) it crystallises the script into a re-runnable command instead of a throwaway heredoc. Tools are one executable file with a parseable comment header, run pre-authed (the operational keyring is merged into their env so they reference `$NAME` and never hardcode a secret), can link to an owning skill pack, and are surfaced every turn as an always-on index (full docs/source on demand via `open-claudia tool show <name>`). Full CLI: `open-claudia tool list|show|add|run|remove`; `/learn` now crystallises the executable part too. Second, a **directed tool-graph** (`core/tool-graph.js`): a "tool B follows tool A" graph kept deliberately separate from the recall graph — for tools the useful signal is the *order* a chain runs in (auth → list → download), so edges are stored and traversed directionally. Each run-sequence reinforces consecutive pairs (Hebbian, decayed nightly, no structural floor so unused chains prune away). `tool show` and the system-prompt index surface "usually followed by …"; `pack show` gains the reverse view (a pack's linked tools); the nightly dream tends the graph (decay + orphan prune) and flags tools whose `--pack` link dangles. Adds `test-tools.js` + `test-tool-graph.js`.
+
 ## v2.6.43
 - **Fix the `🧠 Recall this turn` banner rendering raw HTML.** The recall debug banner (from `/recall on`) is built with `<b>` tags and HTML-escaped names, but its two `send()` calls in `runner.js` omitted the Telegram `parseMode: "HTML"` opts that every normal reply already passes via `telegramHtmlOpts()` — so the tags and `&amp;` entities showed up literally in chat instead of rendering. Both recall sends now pass `telegramHtmlOpts()`, matching the rest of the reply path. Display-only; no change to recall behaviour itself.
 

package/bin/cli.js

@@ -284,6 +284,11 @@ switch (command) {
     break;
   }
 
+  case "tool": {
+    require("./tool").run(args.slice(1));
+    break;
+  }
+
   case "entity": {
     require("./entity").run(args.slice(1));
     break;
@@ -365,6 +370,7 @@ Memory tools:
   open-claudia transcript-window <pattern>   Search project transcript, show hits with context
                                              (alias: tw; --help for options)
   open-claudia pack list|show|match|archive|restore|archived  Context packs: living topic docs (skills + memory)
+  open-claudia tool list|show|add|run|remove Reusable tools: executable scripts the agent saves & re-runs (keyring preauth)
   open-claudia entity list|show|match|note   Entity notes: people/places/projects memory
   open-claudia lessons list|add|remove|show  Always-loaded learned rules (cross-cutting, promoted after a miss)
   open-claudia ideas list|add|remove|show    Self-improvement backlog (captured by the nightly dream)

package/bin/pack.js

@@ -102,6 +102,16 @@ function run(args) {
       const prov = packs.readProvenance(p.dir);
       const authored = packs.SECTIONS.map((s) => `${s}=${prov.sections[s] || "user"}`).join("  ");
       console.log(`\n# provenance: ${authored}${prov.lastWriter ? `  (last: ${prov.lastWriter} ${prov.ts})` : ""}`);
+      // Reverse view: the runnable siblings of this pack's prose. A pack's
+      // Procedure documents *how*; a linked tool *is* the how. Surfacing them
+      // here keeps the doc and its crystallised commands discoverable together.
+      try {
+        const linked = require("../core/tools").listTools().filter((t) => t.pack === p.dir);
+        if (linked.length) {
+          console.log(`\n# tools (${linked.length}) — run with 'open-claudia tool run <name>':`);
+          for (const t of linked) console.log(`#   ${t.name} — ${t.description || "(no description)"}`);
+        }
+      } catch (e) { /* tools optional */ }
       break;
     }
 

package/bin/tool.js

@@ -0,0 +1,148 @@
+// CLI: manage and run reusable tools — executable scripts the agent saves so a
+// procedure it worked out once becomes a re-runnable command, not a re-typed
+// heredoc. The executable sibling of context packs (`open-claudia pack`).
+//
+//   open-claudia tool list                       — index (name — description [skill])
+//   open-claudia tool show <name>                — full docs, path, keyring status
+//   open-claudia tool add <path> [--name n]      — register a script as a tool
+//       [--pack <dir>] [--desc "..."] [--requires "k1,k2"] [--usage "..."]
+//   open-claudia tool run <name> [args...]       — run it with keyring pre-loaded
+//   open-claudia tool remove <name>              — delete one
+//   open-claudia tool path                       — print the tools directory
+//
+// Credentials: a tool runs with the operational keyring merged into its env, so
+// reference creds as $NAME inside the script. `open-claudia keyring list` shows
+// what's available; never hardcode secrets in a tool.
+
+const { spawnSync } = require("child_process");
+const tools = require("../core/tools");
+
+// Minimal flag parser: pulls --key value (and --key=value) out of argv, returns
+// { positional, flags }.
+function parseFlags(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq >= 0) { flags[a.slice(2, eq)] = a.slice(eq + 1); }
+      else { flags[a.slice(2)] = argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : true; }
+    } else positional.push(a);
+  }
+  return { positional, flags };
+}
+
+function run(args) {
+  const cmd = (args[0] || "list").toLowerCase();
+  const rest = args.slice(1);
+
+  switch (cmd) {
+    case "list":
+    case "ls": {
+      const all = tools.listTools();
+      if (all.length === 0) {
+        return console.log(`No tools yet (${tools.TOOLS_DIR}).\nSave one with: open-claudia tool add <script-path> --pack <skill>`);
+      }
+      console.log(`${all.length} reusable tool(s) — run via 'open-claudia tool run <name>':\n`);
+      for (const t of all) {
+        const skill = t.pack ? `  [skill: ${t.pack}]` : "";
+        console.log(`• ${t.name} — ${t.description || "(no description)"}${skill}`);
+      }
+      console.log(`\nDocs: open-claudia tool show <name>   ·   Dir: ${tools.TOOLS_DIR}`);
+      break;
+    }
+
+    case "show":
+    case "cat": {
+      const name = rest[0];
+      if (!name) { console.error("Usage: tool show <name>"); process.exitCode = 1; return; }
+      const t = tools.findTool(name);
+      if (!t) { console.error(`No tool named "${name}". Run: open-claudia tool list`); process.exitCode = 1; return; }
+      console.log(`Tool: ${t.name}`);
+      if (t.description) console.log(`Description: ${t.description}`);
+      if (t.pack) console.log(`Skill pack: ${t.pack}  (open-claudia pack show ${t.pack})`);
+      console.log(`Usage: open-claudia tool run ${t.name}${t.usage ? "   (" + t.usage + ")" : ""}`);
+      if (t.requires.length) {
+        const missing = tools.missingRequires(t);
+        const status = missing.length ? `MISSING: ${missing.join(", ")} — set with 'open-claudia keyring set'` : "all present in keyring";
+        console.log(`Requires keyring keys: ${t.requires.join(", ")}  (${status})`);
+      }
+      console.log(`File: ${t.file}${t.executable ? "" : "  (not executable!)"}`);
+      // Directed tool-graph: what tends to run right after / before this one.
+      try {
+        const graph = require("../core/tool-graph");
+        const fmt = (rows) => rows.map((r) => `${r.name} (${r.weight.toFixed(1)})`).join(", ");
+        const after = graph.followers(t.name);
+        const before = graph.predecessors(t.name);
+        if (after.length) console.log(`Often followed by: ${fmt(after)}`);
+        if (before.length) console.log(`Often preceded by: ${fmt(before)}`);
+      } catch (e) { /* graph optional (old node) */ }
+      console.log(`\n----- source -----\n${t.content}`);
+      break;
+    }
+
+    case "add":
+    case "save": {
+      const { positional, flags } = parseFlags(rest);
+      const srcPath = positional[0];
+      if (!srcPath) {
+        console.error('Usage: tool add <path> [--name n] [--pack dir] [--desc "..."] [--requires "k1,k2"] [--usage "..."]');
+        process.exitCode = 1; return;
+      }
+      try {
+        const t = tools.addTool(srcPath, {
+          name: typeof flags.name === "string" ? flags.name : undefined,
+          pack: typeof flags.pack === "string" ? flags.pack : undefined,
+          description: typeof flags.desc === "string" ? flags.desc : (typeof flags.description === "string" ? flags.description : undefined),
+          requires: typeof flags.requires === "string" ? flags.requires.split(/[,\s]+/).filter(Boolean) : undefined,
+          usage: typeof flags.usage === "string" ? flags.usage : undefined,
+        });
+        console.log(`Saved tool "${t.name}"${t.pack ? ` (skill: ${t.pack})` : ""}.`);
+        console.log(`Run it: open-claudia tool run ${t.name}`);
+        if (t.requires.length) {
+          const missing = tools.missingRequires(t);
+          if (missing.length) console.log(`Note: missing keyring keys it needs: ${missing.join(", ")}`);
+        }
+      } catch (e) {
+        console.error(`Could not add tool: ${e.message}`); process.exitCode = 1;
+      }
+      break;
+    }
+
+    case "run":
+    case "exec": {
+      const name = rest[0];
+      if (!name) { console.error("Usage: tool run <name> [args...]"); process.exitCode = 1; return; }
+      const t = tools.findTool(name);
+      if (!t) { console.error(`No tool named "${name}". Run: open-claudia tool list`); process.exitCode = 1; return; }
+      const missing = tools.missingRequires(t);
+      if (missing.length) {
+        console.error(`Cannot run ${t.name}: missing keyring keys ${missing.join(", ")}. Set them with 'open-claudia keyring set <name> <value>'.`);
+        process.exitCode = 1; return;
+      }
+      const r = spawnSync(t.file, rest.slice(1), { stdio: "inherit", env: tools.runEnv() });
+      if (r.error) { console.error(`Failed to run ${t.name}: ${r.error.message}`); process.exitCode = 1; return; }
+      process.exitCode = typeof r.status === "number" ? r.status : 1;
+      break;
+    }
+
+    case "remove":
+    case "rm": {
+      const name = rest[0];
+      if (!name) { console.error("Usage: tool remove <name>"); process.exitCode = 1; return; }
+      const removed = tools.removeTool(name);
+      console.log(removed ? `Removed tool "${removed.name}".` : `No tool named "${name}".`);
+      break;
+    }
+
+    case "path":
+      console.log(tools.TOOLS_DIR);
+      break;
+
+    default:
+      console.log('Usage: open-claudia tool [list | show <name> | add <path> [flags] | run <name> [args] | remove <name> | path]');
+  }
+}
+
+module.exports = { run };

package/core/dream.js

@@ -681,6 +681,7 @@ function writeDreamReport(data) {
       sec.push("", "### Proposed (not applied — DREAM_SELF_APPLY=off)", "```json", JSON.stringify(data.introspection.proposed, null, 2), "```");
     }
     if (data.graphNote) sec.push("", data.graphNote);
+    if (data.toolNote) sec.push("", data.toolNote);
     if (data.staleNote) sec.push("", data.staleNote);
     if (data.backupRoot) sec.push("", `Backups: ${data.backupRoot}`);
     const block = sec.join("\n") + "\n\n---\n\n";
@@ -825,6 +826,25 @@ async function runDream({ trigger = "manual" } = {}) {
       }
     } catch (e) { /* graph is best-effort */ }
 
+    // Tool hygiene: tend the directed tool-graph (decay reinforced follows-edges,
+    // prune faded/orphaned ones) and flag tools whose --pack link now dangles.
+    // Read-only toward the tools themselves — a tool is never auto-deleted (that's
+    // destructive); we just surface the breakage for the user to re-link or remove.
+    let toolNote = "";
+    try {
+      const toolsLib = require("./tools");
+      const tg = require("./tool-graph").tend(toolsLib);
+      const bits = [];
+      if (tg.edges || tg.decayed || tg.pruned) {
+        bits.push(`🔧 Tool graph: ${tg.edges} edges / ${tg.nodes} nodes (decayed ${tg.decayed}, pruned ${tg.pruned}).`);
+      }
+      const dangling = toolsLib.listTools().filter((t) => t.pack && !packs.readPack(t.pack));
+      if (dangling.length) {
+        bits.push(`🔗 ${dangling.length} tool(s) link a missing skill pack: ${dangling.map((t) => `${t.name}→${t.pack}`).join(", ")} — re-link with --pack or remove.`);
+      }
+      toolNote = bits.join("\n");
+    } catch (e) { /* tool graph is best-effort (old node) */ }
+
     const staleNote = staleTaskReport();
     const dreamLines = consolidationLines.concat(introApplied);
 
@@ -832,7 +852,7 @@ async function runDream({ trigger = "manual" } = {}) {
       model: DREAM_MODEL, effort: DREAM_EFFORT, trigger,
       consolidation: { report: decision.report, lines: consolidationLines },
       introspection: { report: introReport, lines: introApplied, proposed: introProposed },
-      graphNote, staleNote, backupRoot,
+      graphNote, toolNote, staleNote, backupRoot,
     });
 
     // Richer chat summary: consolidation + introspection narrative + what
@@ -846,12 +866,13 @@ async function runDream({ trigger = "manual" } = {}) {
       if (n) parts.push(`📋 ${n} self-improvement change(s) staged for your OK (DREAM_SELF_APPLY=off) — see the log below.`);
     }
     if (graphNote) parts.push(graphNote);
+    if (toolNote) parts.push(toolNote);
     if (staleNote) parts.push(staleNote);
     if (dreamLines.length) parts.push(`🗄 Anything changed or merged away is backed up under ${backupRoot}`);
     if (reportPath) parts.push(`📔 Full dream log: ${reportPath}`);
     const message = parts.length ? parts.join("\n\n") : "";
 
-    return { applied: dreamLines, report, introReport, message, staleNote, graphNote, reportPath, trigger };
+    return { applied: dreamLines, report, introReport, message, staleNote, graphNote, toolNote, reportPath, trigger };
   } finally {
     _dreaming = false;
   }

package/core/handlers.js

@@ -1217,7 +1217,8 @@ register({
       `First check the already-injected packs and 'open-claudia pack list' for a pack this work belongs to; if one fits, fold the reusable how-to into that pack's Procedure section (exact commands in order, prerequisites, pitfalls) and append a dated Journal line — edit the PACK.md directly. ` +
       `Only if no pack fits, create a new one: 'open-claudia pack' has no create subcommand, so write ~/.open-claudia/packs/<kebab-name>/PACK.md following the four-section format (Stance, Procedure, State, Journal) with name + a when-to-use description in the frontmatter. Give it an ACTIVITY-oriented name and description (what you DO — the verbs, tools, and artifacts) so it is findable from other projects by the work being done, not by a project name; and if this how-to came from a specific project, add a 'learned_on: <project-pack-dir>' frontmatter line so its cross-project reuse can be tracked. ` +
       `Then mark that pack as a reusable skill so it is always surfaced in future conversations: run 'open-claudia pack skill <dir> on'. This flags it as a reusable ability and adds it to the always-on skill index (name + description); the Procedure still loads on demand. ` +
-      `No secrets or tokens. When done, reply with one short line naming the pack you created or updated and what it covers. ` +
+      `CRUCIAL — also crystallise the EXECUTABLE part: if the work involved a script, API call, or any repeatable command sequence you wrote inline (a heredoc, a one-off .py/.sh, a curl chain), turn it into a reusable tool instead of leaving it to be re-typed. Write the script to a file (parameterise the bits that vary; read any credential from the env as $NAME rather than hardcoding), then register it with 'open-claudia tool add <path> --pack <dir> --desc "..." [--requires "key1,key2"] [--usage "..."]', linking it to the pack you just touched. Reference creds by their keyring names (see 'open-claudia keyring list'); never write a secret into the tool. The tool is the runnable form of the pack's Procedure — save both. ` +
+      `No secrets or tokens in packs OR tools. When done, reply with one short line naming the pack you created or updated, any tool you saved, and what it covers. ` +
       `If the recent work is genuinely not reusable, say so instead of forcing a skill.`;
     await runClaude(prompt, currentState().currentSession.dir, env.messageId);
   },

package/core/runner.js

@@ -27,6 +27,7 @@ const loopback = require("./loopback");
 const skillsLib = require("./skills");
 const packsLib = require("./packs");
 const entitiesLib = require("./entities");
+const toolsLib = require("./tools");
 const packReview = require("./pack-review");
 const { recallNodeFromPath } = require("./recall/read-signal");
 const {
@@ -314,6 +315,15 @@ async function buildClaudeArgs(prompt, opts = {}) {
   if (settings.permissionMode) args.push("--permission-mode", settings.permissionMode);
   else args.push("--dangerously-skip-permissions");
   if (settings.worktree) args.push("--worktree");
+  // Voice turns stream partial text so the spoken reply can start mid-generation
+  // (see the streaming-out handler in the runner). Strictly gated to the voice
+  // channel — zero behaviour change for Telegram/Kazee.
+  if (state.lastInputWasVoice) {
+    try {
+      const { currentTransport } = require("./context");
+      if (currentTransport() === "voice") args.push("--include-partial-messages");
+    } catch { /* context not ready — skip streaming flag */ }
+  }
   // Dynamic state rides in the user prompt so the appended system prompt
   // stays byte-stable across turns and the prompt-cache prefix survives.
   args.push(await promptWithDynamicContext(prompt));
@@ -813,6 +823,50 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
   state.statusMessageId = null;
   state.streamBuffer = "";
   let assistantText = "";
+
+  // Voice streaming-out: on voice turns we speak each finished sentence as it is
+  // generated (off the partial text_delta events) so the first audio plays while
+  // the rest of the reply is still being written — far lower time-to-first-sound
+  // than synthesizing one pass over the whole reply at the end. Reads the delta
+  // stream only; the text/transcript channel still reads whole-message events, so
+  // chat transports are completely unaffected.
+  let voiceStreaming = false;
+  try {
+    const { currentTransport } = require("./context");
+    voiceStreaming = !!state.lastInputWasVoice && currentTransport() === "voice";
+  } catch { voiceStreaming = false; }
+  let spokenBuf = "";                 // text_delta accumulator awaiting a sentence boundary
+  let ttsChain = Promise.resolve();   // ordered send queue so clips play in order
+  let spokeAnyStreamed = false;
+  const SPOKEN_MIN_CHARS = 40;        // don't fire TTS on tiny fragments ("Hi.")
+  function dispatchSpoken(text) {
+    const clean = redactSensitive(text);
+    if (!clean.trim()) return;
+    spokeAnyStreamed = true;
+    const synthP = synthSentenceMp3(clean); // start synth now (parallel)
+    ttsChain = ttsChain.then(async () => {  // but send strictly in order
+      try { const clip = await synthP; if (clip) await sendVoice(clip); }
+      catch (e) { console.error("voice stream clip failed:", e.message); }
+    });
+  }
+  function pumpSpoken(flush) {
+    // Cut the smallest prefix that ends in a sentence terminator and is at least
+    // SPOKEN_MIN_CHARS long, dispatch it, repeat. On flush, send whatever remains.
+    while (true) {
+      const re = /[.!?]+(?=\s|$)/g;
+      let idx = -1, m;
+      while ((m = re.exec(spokenBuf)) !== null) {
+        const end = m.index + m[0].length;
+        if (end >= SPOKEN_MIN_CHARS) { idx = end; break; }
+      }
+      if (idx === -1) break;
+      const sentence = spokenBuf.slice(0, idx).trim();
+      spokenBuf = spokenBuf.slice(idx).replace(/^\s+/, "");
+      if (sentence) dispatchSpoken(sentence);
+    }
+    if (flush) { const tail = spokenBuf.trim(); spokenBuf = ""; if (tail) dispatchSpoken(tail); }
+  }
+
   let toolUses = [];
   let currentTool = null;
   let currentToolDetail = "";
@@ -857,6 +911,12 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
           else notifySkill(`entity:${entSlug}`, `👤 New entity noted: ${entSlug} — open-claudia entity show ${entSlug} to peek.`);
           return;
         }
+        const toolName2 = toolsLib.toolNameFromPath(filePath);
+        if (toolName2) {
+          if (toolsLib.findTool(toolName2)) notifySkill(`tool:${toolName2}`, `🔧 Updating tool: ${toolName2} — open-claudia tool show ${toolName2} to inspect.`);
+          else notifySkill(`tool:${toolName2}`, `🔧 New tool: ${toolName2} — open-claudia tool run ${toolName2} to use it.`);
+          return;
+        }
         const dir = skillsLib.skillNameFromPath(filePath);
         if (!dir) return;
         // The tool_use event precedes the actual write, so existence now
@@ -874,6 +934,11 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
   // Nodes the agent actually OPENED this turn (📖). This is the co-use signal
   // the recall graph reinforces on — actually-read, not merely surfaced.
   const openedThisTurn = new Set();
+  // Reusable tools the agent RAN this turn, in order. Feeds the directed
+  // tool-graph (core/tool-graph.js): consecutive runs become follows-edges so
+  // "you ran X — you usually run Y next" can be surfaced. Order matters here
+  // (unlike openedThisTurn, a Set), because a tool chain is a pipeline.
+  const toolRunsThisTurn = [];
   const noteRecallFromShell = (command) => {
     try {
       const cmd = String(command || "");
@@ -895,6 +960,11 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
         openedThisTurn.add(`entity:${slug}`);
         notifySkill(`recall:entity:${slug}`, `📖 Recalled my notes on: ${name}`);
       }
+      // `open-claudia tool run|exec <name>` — record the run for the directed
+      // tool-graph. Only the name is captured (args are noise for "what runs
+      // next"); the end-of-turn block reinforces consecutive pairs.
+      const toolRe = /\btool\s+(?:run|exec)\s+["']?([a-z0-9][\w.-]*)/gi;
+      while ((m = toolRe.exec(cmd))) toolRunsThisTurn.push(m[1]);
     } catch (e) { /* announcements are best-effort */ }
   };
 
@@ -1003,6 +1073,15 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
     const lastNewline = state.streamBuffer.lastIndexOf("\n");
     state.streamBuffer = lastNewline >= 0 ? state.streamBuffer.slice(lastNewline + 1) : state.streamBuffer;
     for (const evt of events) {
+      // Voice streaming-out: speak finished sentences as the model writes them.
+      // Only text_delta is spoken; thinking_delta and tool events are ignored.
+      if (voiceStreaming && evt.type === "stream_event"
+          && evt.event?.type === "content_block_delta"
+          && evt.event.delta?.type === "text_delta"
+          && typeof evt.event.delta.text === "string") {
+        spokenBuf += evt.event.delta.text;
+        pumpSpoken(false);
+      }
       if (evt.type === "assistant" && evt.message?.usage) {
         const callPrefix = usageParts(evt.message.usage, settings.backend || "claude").context;
         if (callPrefix > peakContextTokens) peakContextTokens = callPrefix;
@@ -1195,25 +1274,37 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
 
       if (state.lastInputWasVoice) {
         state.lastInputWasVoice = false;
-        // Spoken replies belong to the hands-free voice channel. On chat
-        // transports (Telegram/Kazee) an auto voice note on every voice
-        // input is unwanted noise, so gate it to the voice channel.
-        const { currentTransport } = require("./context");
-        if (currentTransport() === "voice") {
-          // Stream the spoken reply sentence-by-sentence so the first audio
-          // plays while the rest still synthesizes — far lower time-to-first-
-          // sound than waiting for one TTS pass over the whole reply.
-          const sentences = splitSentences(finalText);
-          let spokeAny = false;
-          for (const sentence of sentences) {
-            const clip = await synthSentenceMp3(sentence);
-            if (clip) { spokeAny = true; await sendVoice(clip); }
-          }
-          if (!spokeAny) {
+        if (voiceStreaming) {
+          // Sentences were already being spoken as the model wrote them. Flush
+          // the trailing partial sentence, wait for the ordered send queue to
+          // drain, then close the turn so the client re-arms the mic.
+          pumpSpoken(true);
+          await ttsChain;
+          if (!spokeAnyStreamed) {
+            // Tool-only / empty turn produced no spoken text — say the final
+            // text once so the user still hears a reply.
             const voicePath = await textToVoice(finalText);
             if (voicePath) await sendVoice(voicePath);
           }
           await sendVoiceEnd();
+        } else {
+          // Non-streamed fallback. Spoken replies belong to the hands-free voice
+          // channel; on chat transports (Telegram/Kazee) an auto voice note on
+          // every voice input is unwanted noise, so gate it to the voice channel.
+          const { currentTransport } = require("./context");
+          if (currentTransport() === "voice") {
+            const sentences = splitSentences(finalText);
+            let spokeAny = false;
+            for (const sentence of sentences) {
+              const clip = await synthSentenceMp3(sentence);
+              if (clip) { spokeAny = true; await sendVoice(clip); }
+            }
+            if (!spokeAny) {
+              const voicePath = await textToVoice(finalText);
+              if (voicePath) await sendVoice(voicePath);
+            }
+            await sendVoiceEnd();
+          }
         }
       }
     } catch (e) {
@@ -1240,6 +1331,16 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
       } catch (e) { /* best-effort */ }
     }
 
+    // Directed tool-graph: a chain of reusable tools run in succession this turn
+    // (auth → list → download) becomes follows-edges, so next time the first
+    // runs we can surface "usually followed by …". Kept in a tool-specific graph
+    // so it never bleeds into recall's spreading activation. Reinforce only on a
+    // successful turn, and only when ≥2 ran (a single run has no succession).
+    if (turnSucceeded && toolRunsThisTurn.length > 1) {
+      try { require("./tool-graph").reinforceSequence(toolRunsThisTurn); }
+      catch (e) { /* best-effort */ }
+    }
+
     // Close the learning loop: when an ABILITY pack is opened in the same turn
     // as a project (context) pack, the ability was demonstrably applied while
     // working on that project. recordCoUse grows the ability's applied_on, which

package/core/system-prompt.js

@@ -66,6 +66,53 @@ function buildSkillIndexBlock() {
   }
 }
 
+// Always-on tool index: the executable sibling of the skill index. Each entry
+// is a real script the agent crystallised from a working procedure, surfaced by
+// name+description every turn (progressive disclosure — full docs/source load on
+// demand via `open-claudia tool show <name>`). Tools run pre-authed: the
+// operational keyring is merged into their env, so a tool references a credential
+// as $NAME and never hardcodes a secret.
+function buildToolIndexBlock() {
+  let listing = "";
+  try {
+    const all = require("./tools").listTools();
+    if (all.length) {
+      // Directed tool-graph: surface the strongest "runs next" follower per tool
+      // so a known chain (auth → list → download) is visible inline. Optional —
+      // absent on old node where node:sqlite is missing.
+      let graph = null;
+      try { graph = require("./tool-graph"); } catch (e) {}
+      listing = "\nTools you already have (run with `open-claudia tool run <name> [args]`; read docs/source with `open-claudia tool show <name>`):\n\n" +
+        all.slice(0, 40)
+          .map((t) => {
+            const skill = t.pack ? ` [skill: ${t.pack}]` : "";
+            const needs = t.requires && t.requires.length ? ` (keyring: ${t.requires.join(", ")})` : "";
+            let next = "";
+            if (graph) {
+              try {
+                const after = graph.followers(t.name, 2).map((r) => r.name);
+                if (after.length) next = ` → usually followed by: ${after.join(", ")}`;
+              } catch (e) {}
+            }
+            return `- ${t.name} — ${t.description || "(no description)"}${needs}${skill}${next}`;
+          })
+          .join("\n") + "\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";
+    }
+  } 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.
+
+- 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.
+${listing}`;
+}
+
 function buildSystemPrompt() {
   const state = currentState();
   const soul = loadSoul();
@@ -160,6 +207,7 @@ Open Claudia learned skills are stored as context packs under ${path.join(CONFIG
 
 If the user asks for a skill by name, do not rely only on the backend harness's native "Available skills" list. First use any Active context pack injected into the current request as the requested Open Claudia skill. If no matching pack was injected, inspect with \`open-claudia pack list\` / \`open-claudia pack show <dir>\` and legacy \`/skills\` paths before saying the skill does not exist.
 ${buildSkillIndexBlock()}
+${buildToolIndexBlock()}
 
 ## Stable Local Paths
 - Bot code: ${path.join(BOT_DIR, "bot.js")}
@@ -232,7 +280,7 @@ Your durable knowledge lives in context packs: living per-topic documents (one p
 
 Alongside packs you keep entity notes: one short file per named person, place, project, org, or system (Notes = current truth, Log = dated observations). Entities matching the incoming message are auto-injected like packs, and the same background reviewer maintains them. Inspect with \`open-claudia entity list\` / \`entity show <slug>\`; edit the files directly (announce in one line) when you learn something durable about someone or something. Same boundaries as packs.
 
-"/learn" asks you to explicitly capture the most recent piece of work: fold it into the matching pack's Procedure section (create a pack only if none fits). Legacy ~/.claude/skills still load if present, but new captures go to packs.
+"/learn" asks you to explicitly capture the most recent piece of work: fold the prose how-to into the matching pack's Procedure section (create a pack only if none fits), AND crystallise any repeatable script into a reusable tool with \`open-claudia tool add ... --pack <dir>\` so the runnable form is saved alongside the prose. Legacy ~/.claude/skills still load if present, but new captures go to packs + tools.
 
 A nightly "dream" pass consolidates memory on a stronger model: it merges duplicate packs, builds umbrella/parent pack trees, tightens descriptions and tags, dedupes entities, and may gently evolve your persona file. Anything merged away is backed up first, and every dream that changes something reports in chat. Trigger it manually with \`open-claudia dream\` (or \`--dry-run\` to preview the decision without applying).
 

package/core/tool-graph.js

@@ -0,0 +1,217 @@
+// Directed tool-usage graph: "tool B often follows tool A". The executable
+// counterpart to the recall graph (core/recall/graph.js), but deliberately
+// SEPARATE and DIRECTED.
+//
+// Why separate: the recall graph spreads activation over packs+entities to pick
+// which MEMORY to surface. Tools are a different corpus with different physics —
+// the useful signal is the ORDER a chain runs in (auth → list → download), not
+// symmetric "these are related". Mixing tool nodes into the recall graph would
+// let a tool fire a pack headline (and vice-versa), which is noise. So tools get
+// their own tiny graph.
+//
+// Why directed: A→B ("B follows A") carries real information that B→A does not.
+// auth-then-fetch is a pipeline; fetch-then-auth is nonsense. Edges are stored
+// and traversed directionally. Each edge carries a Hebbian `weight` bumped on
+// co-use and decayed over time; unlike pack edges there is no structural floor,
+// so a chain that stops being used eventually decays away and is pruned.
+
+const fs = require("fs");
+const path = require("path");
+
+let DatabaseSync = null;
+try { ({ DatabaseSync } = require("node:sqlite")); } catch (e) { /* old node — graph disabled */ }
+
+const CONFIG_DIR = require("../config-dir");
+const GRAPH_DB = process.env.TOOL_GRAPH_DB
+  ? path.resolve(process.env.TOOL_GRAPH_DB)
+  : path.join(CONFIG_DIR, "tool-graph.db");
+
+// Tunables (overridable via dream knobs later).
+const DEFAULTS = {
+  halfLifeDays: 45,   // Hebbian weight half-life for decay()
+  pruneBelow: 0.15,   // edges decayed under this are dropped (no structural floor)
+};
+
+let _db = null;
+
+function available() { return !!DatabaseSync; }
+
+function openDb() {
+  if (!DatabaseSync) return null;
+  if (_db) return _db;
+  try {
+    fs.mkdirSync(path.dirname(GRAPH_DB), { recursive: true, mode: 0o700 });
+    const db = new DatabaseSync(GRAPH_DB);
+    try { fs.chmodSync(GRAPH_DB, 0o600); } catch (e) {}
+    db.exec("PRAGMA journal_mode=WAL");
+    db.exec("PRAGMA busy_timeout=3000");
+    db.exec(`CREATE TABLE IF NOT EXISTS tool_edges (
+      src TEXT NOT NULL,
+      dst TEXT NOT NULL,
+      weight REAL NOT NULL DEFAULT 1,
+      last_reinforced TEXT,
+      created TEXT,
+      PRIMARY KEY (src, dst)
+    )`);
+    db.exec("CREATE INDEX IF NOT EXISTS tool_edges_src ON tool_edges (src)");
+    db.exec("CREATE INDEX IF NOT EXISTS tool_edges_dst ON tool_edges (dst)");
+    _db = db;
+    return db;
+  } catch (e) {
+    return null;
+  }
+}
+
+function now() { return new Date().toISOString(); }
+
+// Directed upsert of a follows-edge src→dst. `bump` adds to the current weight
+// (Hebbian) and stamps last_reinforced; with no bump it just ensures the edge
+// exists at `weight` (default 1).
+function addFollow(src, dst, opts = {}) {
+  const db = openDb();
+  if (!db || !src || !dst || src === dst) return false;
+  const bump = Number.isFinite(opts.bump) ? opts.bump : 0;
+  const weight = Number.isFinite(opts.weight) ? opts.weight : 1;
+  try {
+    const existing = db.prepare("SELECT weight FROM tool_edges WHERE src=? AND dst=?").get(src, dst);
+    if (existing) {
+      const next = bump ? existing.weight + bump : Math.max(existing.weight, weight);
+      if (bump) {
+        db.prepare("UPDATE tool_edges SET weight=?, last_reinforced=? WHERE src=? AND dst=?")
+          .run(next, now(), src, dst);
+      } else {
+        db.prepare("UPDATE tool_edges SET weight=? WHERE src=? AND dst=?").run(next, src, dst);
+      }
+    } else {
+      // No structural floor for tools: a brand-new edge is worth exactly its
+      // first co-occurrence (bump), or the explicit `weight` for a pure ensure.
+      const initial = bump ? bump : weight;
+      db.prepare("INSERT INTO tool_edges (src, dst, weight, last_reinforced, created) VALUES (?,?,?,?,?)")
+        .run(src, dst, initial, bump ? now() : null, now());
+    }
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+// Reinforce an ordered run of tools: for [a, b, c] strengthen a→b and b→c (only
+// immediate succession — that's the cleanest "what runs next" signal). Repeated
+// names in a row are collapsed so a tool re-run in a loop doesn't self-link.
+function reinforceSequence(names, amount = 1) {
+  const seq = (names || []).filter(Boolean);
+  let last = null;
+  for (const name of seq) {
+    if (last && last !== name) addFollow(last, name, { bump: amount });
+    last = name;
+  }
+}
+
+function removeEdge(src, dst) {
+  const db = openDb();
+  if (!db) return false;
+  try { db.prepare("DELETE FROM tool_edges WHERE src=? AND dst=?").run(src, dst); return true; }
+  catch (e) { return false; }
+}
+
+function allEdges() {
+  const db = openDb();
+  if (!db) return [];
+  try { return db.prepare("SELECT src, dst, weight, last_reinforced FROM tool_edges").all(); }
+  catch (e) { return []; }
+}
+
+// Tools that tend to follow `name`, strongest first. This is the surfaced
+// signal: "you ran X — you usually run these next".
+function followers(name, limit = 5) {
+  const db = openDb();
+  if (!db || !name) return [];
+  try {
+    return db.prepare("SELECT dst AS name, weight FROM tool_edges WHERE src=? ORDER BY weight DESC LIMIT ?")
+      .all(name, limit);
+  } catch (e) { return []; }
+}
+
+// Tools that tend to precede `name` (the inverse view).
+function predecessors(name, limit = 5) {
+  const db = openDb();
+  if (!db || !name) return [];
+  try {
+    return db.prepare("SELECT src AS name, weight FROM tool_edges WHERE dst=? ORDER BY weight DESC LIMIT ?")
+      .all(name, limit);
+  } catch (e) { return []; }
+}
+
+// Exponential time decay. Tools have no structural floor, so edges decay toward
+// zero and are pruned once under `pruneBelow` — a chain that fell out of use
+// disappears instead of lingering as stale advice.
+function decay({ halfLifeDays = DEFAULTS.halfLifeDays, pruneBelow = DEFAULTS.pruneBelow } = {}) {
+  const db = openDb();
+  if (!db) return { decayed: 0, pruned: 0 };
+  const rows = allEdges();
+  const nowMs = Date.now();
+  const ln2 = Math.log(2);
+  let decayed = 0, pruned = 0;
+  for (const e of rows) {
+    if (!e.last_reinforced) continue;
+    const ageDays = (nowMs - Date.parse(e.last_reinforced)) / 86400000;
+    if (!(ageDays > 0)) continue;
+    const factor = Math.exp(-ln2 * ageDays / Math.max(1, halfLifeDays));
+    const next = e.weight * factor;
+    if (next < pruneBelow) {
+      if (removeEdge(e.src, e.dst)) pruned++;
+      continue;
+    }
+    if (Math.abs(next - e.weight) > 1e-6) {
+      try {
+        db.prepare("UPDATE tool_edges SET weight=? WHERE src=? AND dst=?").run(next, e.src, e.dst);
+        decayed++;
+      } catch (e2) {}
+    }
+  }
+  return { decayed, pruned };
+}
+
+// Drop edges whose endpoints are no longer registered tools (a tool was removed
+// or renamed). Keeps the graph from pointing at things that can't be run.
+function pruneOrphans(toolsLib) {
+  const db = openDb();
+  if (!db) return 0;
+  let live;
+  try { live = new Set(toolsLib.listTools().map((t) => t.name)); }
+  catch (e) { return 0; }
+  if (!live.size) return 0;
+  let removed = 0;
+  for (const e of allEdges()) {
+    if (!live.has(e.src) || !live.has(e.dst)) {
+      if (removeEdge(e.src, e.dst)) removed++;
+    }
+  }
+  return removed;
+}
+
+// Nightly maintenance (called by the dream): decay reinforced weights and drop
+// orphaned/faded edges. Deterministic + safe — no model needed.
+function tend(toolsLib, opts = {}) {
+  const { decayed, pruned } = decay(opts);
+  const orphaned = toolsLib ? pruneOrphans(toolsLib) : 0;
+  return { decayed, pruned: pruned + orphaned, ...stats() };
+}
+
+function stats() {
+  const rows = allEdges();
+  const nodes = new Set();
+  for (const e of rows) { nodes.add(e.src); nodes.add(e.dst); }
+  return { edges: rows.length, nodes: nodes.size };
+}
+
+// Test seam.
+function _resetForTest() { if (_db) { try { _db.close(); } catch (e) {} } _db = null; }
+
+module.exports = {
+  DEFAULTS, GRAPH_DB,
+  available, openDb,
+  addFollow, reinforceSequence, removeEdge, allEdges,
+  followers, predecessors, decay, pruneOrphans, tend, stats,
+  _resetForTest,
+};

package/core/tools.js

@@ -0,0 +1,227 @@
+// Reusable tools: executable scripts the agent crystallises as it works, so a
+// procedure it figured out once (hit an API, drive an interface, transform a
+// file) becomes a re-runnable command next time instead of a throwaway heredoc.
+//
+// This is the executable sibling of context packs. A pack's Procedure section
+// documents *how* in prose; a tool *is* the how — a real file you run. Tools
+// are surfaced in the system prompt as an always-on index (like skill packs)
+// and read on demand via `open-claudia tool show <name>` (progressive
+// disclosure). Each tool can name an owning skill pack so the two stay linked.
+//
+// Preauth: tools run with the operational keyring merged into their env (see
+// runEnv()), exactly like the agent's own subprocess. So a tool references a
+// credential as $inet_central_user and never hardcodes a secret. The keyring is
+// already a managed .env (plaintext + chmod 600 + log redaction); tools inherit
+// that model rather than inventing a second one.
+
+const fs = require("fs");
+const path = require("path");
+const CONFIG_DIR = require("../config-dir");
+
+const TOOLS_DIR = process.env.TOOLS_DIR ? path.resolve(process.env.TOOLS_DIR) : path.join(CONFIG_DIR, "tools");
+
+// Marker line that makes a script a registered tool, plus the header fields we
+// parse from the leading comment block. Language-agnostic: we accept "#" (sh,
+// python, ruby) and "//" (js, ts, go) comment prefixes.
+const MARKER = "open-claudia-tool";
+const HEADER_KEYS = ["description", "pack", "requires", "usage"];
+
+function ensureDir() {
+  fs.mkdirSync(TOOLS_DIR, { recursive: true, mode: 0o700 });
+}
+
+function sanitizeName(name) {
+  return String(name || "").toLowerCase().trim()
+    .replace(/[^a-z0-9._-]+/g, "-").replace(/^[-.]+|[-.]+$/g, "").slice(0, 60);
+}
+
+// Strip a leading comment prefix ("# " / "// ") from a header line. Returns the
+// remainder, or null if the line is not a comment (header block has ended).
+function uncomment(line) {
+  const m = String(line).match(/^\s*(#|\/\/)\s?(.*)$/);
+  return m ? m[2] : null;
+}
+
+// Parse the leading comment header of a tool script. The block runs from the
+// first comment line and ends at the first non-comment, non-shebang line. A
+// script is only a tool if the block contains an "open-claudia-tool: <name>"
+// line.
+function parseHeader(content) {
+  const out = { name: "", description: "", pack: "", requires: [], usage: "" };
+  const lines = String(content || "").split("\n");
+  let started = false;
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (i === 0 && raw.startsWith("#!")) continue; // shebang
+    const body = uncomment(raw);
+    if (body === null) {
+      if (started) break;       // header block ended
+      if (raw.trim() === "") continue; // tolerate a blank line before the block
+      break;                    // first real code line, no header → not a tool
+    }
+    started = true;
+    const kv = body.match(/^([a-zA-Z-]+)\s*:\s*(.*)$/);
+    if (!kv) continue;
+    const key = kv[1].toLowerCase();
+    const val = kv[2].trim();
+    if (key === MARKER) out.name = sanitizeName(val);
+    else if (key === "requires") out.requires = val.split(/[,\s]+/).map((s) => s.trim()).filter(Boolean);
+    else if (HEADER_KEYS.includes(key)) out[key] = val;
+  }
+  return out.name ? out : null;
+}
+
+function toolFile(name) {
+  return path.join(TOOLS_DIR, sanitizeName(name));
+}
+
+function readTool(name) {
+  const file = toolFile(name);
+  let content;
+  try { content = fs.readFileSync(file, "utf-8"); } catch (e) { return null; }
+  const header = parseHeader(content);
+  if (!header) return null;
+  let stat = null;
+  try { stat = fs.statSync(file); } catch (e) {}
+  return {
+    name: header.name || sanitizeName(name),
+    description: header.description || "",
+    pack: header.pack || "",
+    requires: header.requires || [],
+    usage: header.usage || "",
+    file,
+    executable: stat ? !!(stat.mode & 0o111) : false,
+    updatedAt: stat ? stat.mtime.toISOString() : "",
+    content,
+  };
+}
+
+function listTools() {
+  let entries;
+  try { entries = fs.readdirSync(TOOLS_DIR); } catch (e) { return []; }
+  const tools = [];
+  for (const name of entries) {
+    if (name.startsWith(".")) continue;
+    try { if (!fs.statSync(path.join(TOOLS_DIR, name)).isFile()) continue; }
+    catch (e) { continue; }
+    const t = readTool(name);
+    if (t) tools.push(t);
+  }
+  tools.sort((a, b) => a.name.localeCompare(b.name));
+  return tools;
+}
+
+function findTool(name) {
+  const needle = sanitizeName(name);
+  if (!needle) return null;
+  return readTool(needle);
+}
+
+// Build the header comment block for a script that doesn't already declare one.
+// Uses the comment prefix that matches the script's shebang/extension.
+function buildHeader(prefix, { name, description, pack, requires, usage }) {
+  const lines = [`${prefix} ${MARKER}: ${name}`];
+  if (description) lines.push(`${prefix} description: ${description}`);
+  if (pack) lines.push(`${prefix} pack: ${pack}`);
+  if (requires && requires.length) lines.push(`${prefix} requires: ${[].concat(requires).join(", ")}`);
+  if (usage) lines.push(`${prefix} usage: ${usage}`);
+  return lines.join("\n");
+}
+
+function commentPrefixFor(content, srcPath) {
+  const first = String(content || "").split("\n")[0] || "";
+  if (/\b(node|deno|bun)\b/.test(first) || /\.(jsx?|tsx?|go)$/i.test(srcPath || "")) return "//";
+  return "#";
+}
+
+// Register a script as a tool. Copies it into TOOLS_DIR under a sanitized name,
+// ensures it carries a header (synthesising one from opts if absent), and makes
+// it executable. Returns the stored tool.
+function addTool(srcPath, opts = {}) {
+  ensureDir();
+  let content;
+  try { content = fs.readFileSync(srcPath, "utf-8"); }
+  catch (e) { throw new Error(`cannot read ${srcPath}: ${e.message}`); }
+
+  let header = parseHeader(content);
+  const name = sanitizeName(opts.name || (header && header.name) || path.basename(srcPath).replace(/\.[^.]+$/, ""));
+  if (!name) throw new Error("tool needs a name (pass --name or add an 'open-claudia-tool:' header line)");
+
+  if (!header) {
+    // No header in the source — synthesise one so the tool is self-documenting.
+    const prefix = commentPrefixFor(content, srcPath);
+    const block = buildHeader(prefix, {
+      name,
+      description: opts.description || "",
+      pack: opts.pack || "",
+      requires: opts.requires || [],
+      usage: opts.usage || "",
+    });
+    const hasShebang = content.startsWith("#!");
+    if (hasShebang) {
+      const nl = content.indexOf("\n");
+      content = content.slice(0, nl + 1) + block + "\n" + content.slice(nl + 1);
+    } else {
+      content = block + "\n" + content;
+    }
+    header = parseHeader(content);
+  } else if (opts.pack && !header.pack) {
+    // Source had a header but no pack link and the caller supplied one — add it.
+    const prefix = commentPrefixFor(content, srcPath);
+    content = content.replace(
+      new RegExp(`((#|//)\\s*${MARKER}:.*\\n)`),
+      `$1${prefix} pack: ${opts.pack}\n`
+    );
+  }
+
+  const dest = toolFile(name);
+  fs.writeFileSync(dest, content, { mode: 0o700 });
+  try { fs.chmodSync(dest, 0o700); } catch (e) {}
+  return readTool(name);
+}
+
+function removeTool(name) {
+  const tool = findTool(name);
+  if (!tool) return null;
+  try { fs.rmSync(tool.file, { force: true }); } catch (e) { return null; }
+  return tool;
+}
+
+// Env for running a tool: the bot's standard subprocess env (PATH + keyring
+// creds merged) so tools are pre-authed the same way the agent is. Falls back to
+// a plain keyring merge if config isn't importable (e.g. standalone test).
+function runEnv() {
+  try { return require("./config").botSubprocessEnv(); }
+  catch (e) {
+    try {
+      const keyring = require("./keyring");
+      return { ...keyring.all(), ...process.env };
+    } catch (e2) { return { ...process.env }; }
+  }
+}
+
+// Which of a tool's required keyring keys are actually present right now — used
+// by `tool show` to warn before a run fails on a missing credential.
+function missingRequires(tool) {
+  if (!tool || !tool.requires || !tool.requires.length) return [];
+  let present;
+  try { present = new Set(require("./keyring").keys()); }
+  catch (e) { present = new Set(Object.keys(process.env)); }
+  return tool.requires.filter((k) => !present.has(k) && process.env[k] === undefined);
+}
+
+// Recognise a Write/Edit aimed at a tool file (for chat announcements).
+function toolNameFromPath(filePath) {
+  if (!filePath) return null;
+  const resolved = path.resolve(String(filePath));
+  const rel = path.relative(TOOLS_DIR, resolved);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
+  if (rel.split(path.sep).length !== 1) return null;
+  return rel;
+}
+
+module.exports = {
+  TOOLS_DIR, MARKER,
+  parseHeader, readTool, listTools, findTool, addTool, removeTool,
+  runEnv, missingRequires, toolNameFromPath, sanitizeName, ensureDir,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "2.6.48",
+  "version": "2.6.50",
   "description": "Your always-on AI coding assistant — Claude Code, Cursor Agent, and OpenAI Codex via Telegram or Kazee Chat",
   "main": "bot.js",
   "bin": {
@@ -9,7 +9,7 @@
   "scripts": {
     "setup": "node setup.js",
     "start": "node bot.js",
-    "test": "OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node -e \"require('./vault'); console.log('OK')\" && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-usage-accounting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-engine.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-graph.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-discoverer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-project-transcripts-smoke.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-abilities.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-extraction.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-couse.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-transfer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-tiers.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-merge-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-learning-e2e.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-pack-nesting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-read-signal.js"
+    "test": "OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node -e \"require('./vault'); console.log('OK')\" && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-usage-accounting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-engine.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-graph.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-discoverer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-project-transcripts-smoke.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-abilities.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-extraction.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-couse.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-transfer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-tiers.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-merge-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-learning-e2e.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-pack-nesting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-read-signal.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tools.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-graph.js"
   },
   "files": [
     "bot.js",
@@ -43,7 +43,9 @@
     "test-ability-merge-guard.js",
     "test-learning-e2e.js",
     "test-pack-nesting.js",
-    "test-read-signal.js"
+    "test-read-signal.js",
+    "test-tools.js",
+    "test-tool-graph.js"
   ],
   "keywords": [
     "claude",

package/test-tool-graph.js

@@ -0,0 +1,97 @@
+// Directed tool-graph: "tool B follows tool A". Unlike the recall graph this is
+// DIRECTED (A→B carries info B→A does not) and has NO structural floor, so an
+// unused chain decays to zero and is pruned. This exercises core/tool-graph.js
+// end to end against an isolated DB so nothing touches the real graph.
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "tool-graph-test-"));
+process.env.TOOL_GRAPH_DB = path.join(tmp, "tool-graph.db");
+
+const graph = require("./core/tool-graph");
+
+// node:sqlite arrived in node 22; on older runtimes the graph is a no-op. Skip
+// cleanly so the suite stays green rather than failing on the environment.
+if (!graph.available()) {
+  console.log("tool-graph OK (node:sqlite unavailable — skipped)");
+  process.exit(0);
+}
+
+// ── reinforceSequence lays directed edges for IMMEDIATE succession only ──
+graph.reinforceSequence(["auth", "list", "download"]);
+let after = graph.followers("auth");
+assert.strictEqual(after.length, 1, "auth has exactly one follower");
+assert.strictEqual(after[0].name, "list", "list follows auth");
+assert.strictEqual(after[0].weight, 1, "a single co-occurrence weighs 1 (no structural floor)");
+
+// non-adjacent pairs are NOT linked — auth→download must not exist
+assert.ok(!graph.followers("auth").some((r) => r.name === "download"), "auth→download skipped (not adjacent)");
+
+// ── directionality: the edge is auth→list, never list→auth ──
+assert.ok(graph.followers("list").some((r) => r.name === "download"), "download follows list");
+assert.ok(!graph.followers("list").some((r) => r.name === "auth"), "auth does NOT follow list (directed)");
+assert.strictEqual(graph.predecessors("download")[0].name, "list", "list precedes download");
+assert.ok(graph.predecessors("list").some((r) => r.name === "auth"), "auth precedes list");
+assert.ok(!graph.predecessors("list").some((r) => r.name === "download"), "download does NOT precede list (directed)");
+
+// ── Hebbian bump: re-running the chain strengthens the same edges ──
+graph.reinforceSequence(["auth", "list", "download"]);
+assert.strictEqual(graph.followers("auth")[0].weight, 2, "second co-use bumps auth→list to 2");
+
+// ── repeated names in a row collapse: a tool re-run in a loop must not self-link ──
+graph.reinforceSequence(["loop", "loop", "loop", "end"]);
+assert.ok(!graph.followers("loop").some((r) => r.name === "loop"), "no loop→loop self-edge");
+assert.strictEqual(graph.followers("loop")[0].name, "end", "loop→end is the only edge from a repeated run");
+
+// ── addFollow guards: src===dst is rejected ──
+assert.strictEqual(graph.addFollow("x", "x"), false, "self-edge refused");
+
+// ── a pure 'ensure' edge (no bump) has no last_reinforced and so survives decay ──
+graph.addFollow("ensure-src", "ensure-dst"); // weight 1, last_reinforced=null
+const ensured = graph.followers("ensure-src");
+assert.strictEqual(ensured[0].weight, 1, "ensure edge weighs 1");
+
+// ── decay: backdate a reinforced edge far into the past, then it prunes (no floor) ──
+const db = graph.openDb();
+const longAgo = new Date(Date.now() - 365 * 86400000).toISOString();
+db.prepare("UPDATE tool_edges SET last_reinforced=? WHERE src=? AND dst=?").run(longAgo, "auth", "list");
+let res = graph.decay({ halfLifeDays: 1, pruneBelow: 0.15 });
+assert.ok(res.pruned >= 1, "a year-old edge under the floor is pruned");
+assert.ok(!graph.followers("auth").some((r) => r.name === "list"), "pruned edge is gone");
+
+// the ensure edge (last_reinforced=null) was skipped by decay, not pruned
+assert.ok(graph.followers("ensure-src").some((r) => r.name === "ensure-dst"), "un-reinforced edge survives decay");
+
+// ── decay that reduces but keeps an edge above the floor ──
+graph.addFollow("warm-a", "warm-b", { bump: 10 });
+const recent = new Date(Date.now() - 30 * 86400000).toISOString();
+db.prepare("UPDATE tool_edges SET last_reinforced=? WHERE src=? AND dst=?").run(recent, "warm-a", "warm-b");
+graph.decay({ halfLifeDays: 30, pruneBelow: 0.15 }); // one half-life → ~5
+const warm = graph.followers("warm-a")[0];
+assert.ok(warm && warm.name === "warm-b", "warm edge survives a single half-life");
+assert.ok(warm.weight < 10 && warm.weight > 0.15, `warm edge decayed but kept (${warm.weight})`);
+
+// ── removeEdge ──
+assert.strictEqual(graph.removeEdge("warm-a", "warm-b"), true, "removeEdge succeeds");
+assert.ok(!graph.followers("warm-a").length, "removed edge gone");
+
+// ── pruneOrphans drops edges whose endpoints are no longer registered tools ──
+graph.reinforceSequence(["live", "dead"]); // 'dead' will not be in the live set
+const fakeLib = { listTools: () => [{ name: "live" }, { name: "end" }, { name: "loop" }, { name: "ensure-src" }, { name: "ensure-dst" }] };
+const removed = graph.pruneOrphans(fakeLib);
+assert.ok(removed >= 1, "edge pointing at an unregistered tool ('dead') is pruned");
+assert.ok(!graph.followers("live").length, "live→dead removed because dead is not a live tool");
+
+// ── tend() is the nightly entry: decays + prunes orphans + returns stats ──
+const t = graph.tend(fakeLib);
+assert.ok(typeof t.edges === "number" && typeof t.nodes === "number", "tend returns stats");
+assert.ok(typeof t.pruned === "number" && typeof t.decayed === "number", "tend returns decay/prune counts");
+
+// ── stats / allEdges sanity ──
+const s = graph.stats();
+assert.strictEqual(s.edges, graph.allEdges().length, "stats edge count matches allEdges");
+
+graph._resetForTest();
+console.log("tool-graph OK");

package/test-tools.js

@@ -0,0 +1,92 @@
+// Reusable tools: a script the agent crystallises must register with a parseable
+// header, run with the keyring merged into its env (preauth), and be findable by
+// the always-on tool index. This exercises the core/tools.js library end to end
+// in an isolated TOOLS_DIR so nothing touches the real ~/.open-claudia/tools.
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "tools-test-"));
+process.env.TOOLS_DIR = path.join(tmp, "tools");
+
+const tools = require("./core/tools");
+
+// ── add a bare script (no header): a header is synthesised from opts, shebang
+//    is preserved on line 1, and the file is made executable ──
+const srcA = path.join(tmp, "hello.sh");
+fs.writeFileSync(srcA, "#!/usr/bin/env bash\necho \"hi $1\"\n");
+const a = tools.addTool(srcA, {
+  name: "hello",
+  description: "say hi",
+  pack: "greetings",
+  requires: ["api_key", "api_secret"],
+  usage: "hello <name>",
+});
+assert.strictEqual(a.name, "hello", "synthesised tool keeps requested name");
+assert.strictEqual(a.description, "say hi", "description parsed back from synthesised header");
+assert.strictEqual(a.pack, "greetings", "pack link parsed back");
+assert.deepStrictEqual(a.requires, ["api_key", "api_secret"], "requires parsed back as a list");
+assert.strictEqual(a.usage, "hello <name>", "usage parsed back");
+assert.ok(a.executable, "stored tool is chmod +x");
+assert.ok(a.content.startsWith("#!/usr/bin/env bash\n"), "shebang stays on line 1");
+assert.ok(/# open-claudia-tool: hello/.test(a.content), "marker line injected with '#' prefix for a shell script");
+
+// ── findTool / listTools see it ──
+assert.strictEqual(tools.findTool("hello").name, "hello", "findTool resolves by name");
+assert.strictEqual(tools.findTool("HELLO").name, "hello", "findTool is case-insensitive (sanitized)");
+assert.ok(tools.listTools().some((t) => t.name === "hello"), "listTools includes the new tool");
+
+// ── a JS source with a shebang gets a '//' comment header, not '#' ──
+const srcB = path.join(tmp, "fetch.js");
+fs.writeFileSync(srcB, "#!/usr/bin/env node\nconsole.log('x');\n");
+const b = tools.addTool(srcB, { name: "fetch", description: "fetch a thing" });
+assert.ok(/\/\/ open-claudia-tool: fetch/.test(b.content), "JS script gets '//' marker prefix");
+assert.strictEqual(b.requires.length, 0, "no requires when none supplied");
+
+// ── a source that already declares its own header is respected; a --pack passed
+//    in is grafted on without clobbering the existing marker ──
+const srcC = path.join(tmp, "self-doc.sh");
+fs.writeFileSync(
+  srcC,
+  "#!/usr/bin/env bash\n# open-claudia-tool: selfdoc\n# description: pre-documented\necho hi\n"
+);
+const c = tools.addTool(srcC, { pack: "linked-pack" });
+assert.strictEqual(c.name, "selfdoc", "existing marker name wins");
+assert.strictEqual(c.description, "pre-documented", "existing description preserved");
+assert.strictEqual(c.pack, "linked-pack", "--pack grafted onto a self-documented script");
+
+// ── missingRequires: keys absent from keyring AND env are reported; present env
+//    keys are not ──
+process.env.api_key = "present";
+delete process.env.api_secret;
+const missing = tools.missingRequires(tools.findTool("hello"));
+assert.ok(!missing.includes("api_key"), "a key present in env is not 'missing'");
+assert.ok(missing.includes("api_secret"), "a key absent everywhere is 'missing'");
+delete process.env.api_key;
+
+// ── runEnv returns an env object (keyring merged or graceful fallback) ──
+const env = tools.runEnv();
+assert.ok(env && typeof env === "object" && env.PATH, "runEnv yields an env object carrying PATH");
+
+// ── toolNameFromPath only recognises a direct child of TOOLS_DIR ──
+assert.strictEqual(
+  tools.toolNameFromPath(path.join(process.env.TOOLS_DIR, "hello")),
+  "hello",
+  "a file directly in TOOLS_DIR resolves to its tool name"
+);
+assert.strictEqual(tools.toolNameFromPath("/etc/passwd"), null, "a path outside TOOLS_DIR → null");
+assert.strictEqual(
+  tools.toolNameFromPath(path.join(process.env.TOOLS_DIR, "sub", "deep")),
+  null,
+  "a nested path under TOOLS_DIR → null"
+);
+
+// ── parseHeader returns null for a script with no marker line ──
+assert.strictEqual(tools.parseHeader("#!/bin/sh\necho hi\n"), null, "no marker → not a tool");
+
+// ── remove ──
+assert.ok(tools.removeTool("hello"), "removeTool returns the removed tool");
+assert.strictEqual(tools.findTool("hello"), null, "removed tool is gone");
+
+console.log("tools OK");