@inetafrica/open-claudia 2.6.47 → 2.6.49

package/core/media.js

@@ -79,4 +79,56 @@ async function textToVoice(text) {
   return sayToVoice(clean);
 }
 
-module.exports = { transcribeAudio, textToVoice, TTS_CMD };
+// Split a reply into sentence-sized chunks for streamed TTS. Tiny fragments are
+// merged into the next chunk so we don't fire a TTS call per "Hi." and end up
+// with choppy playback. Returns cleaned, non-empty chunks.
+function splitSentences(text, minLen = 30) {
+  const clean = cleanForTTS(text);
+  if (!clean) return [];
+  const raw = clean.match(/[^.!?]+[.!?]+|\S[^.!?]*$/g) || [clean];
+  const out = [];
+  let buf = "";
+  for (const piece of raw) {
+    buf = (buf ? `${buf} ${piece.trim()}` : piece.trim()).trim();
+    if (buf.length >= minLen) { out.push(buf); buf = ""; }
+  }
+  if (buf) {
+    if (out.length) out[out.length - 1] = `${out[out.length - 1]} ${buf}`.trim();
+    else out.push(buf);
+  }
+  return out.filter(Boolean);
+}
+
+// Synthesize one already-short chunk to a directly-playable mp3 (no transcode).
+// Used by the voice channel's streamed replies. Falls back to the ogg path
+// (textToVoice) on no-key/error so callers always get a playable file or null.
+async function synthSentenceMp3(text) {
+  const clean = cleanForTTS(text);
+  if (!clean) return null;
+  if (!ELEVENLABS_API_KEY) return sayToVoice(clean); // ogg fallback
+  try {
+    const res = await fetch(`https://api.elevenlabs.io/v1/text-to-speech/${ELEVENLABS_VOICE_ID}`, {
+      method: "POST",
+      headers: { "xi-api-key": ELEVENLABS_API_KEY, "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text: clean,
+        model_id: ELEVENLABS_MODEL,
+        voice_settings: { stability: 0.5, similarity_boost: 0.85, style: 0.5, use_speaker_boost: true },
+      }),
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      console.error(`ElevenLabs TTS failed: ${res.status} ${body}`.slice(0, 300));
+      return sayToVoice(clean);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    const mp3Path = path.join(TEMP_DIR, `tts-${Date.now()}-${Math.random().toString(36).slice(2, 6)}.mp3`);
+    fs.writeFileSync(mp3Path, buf);
+    return mp3Path;
+  } catch (e) {
+    console.error("ElevenLabs TTS error:", e.message);
+    return sayToVoice(clean);
+  }
+}
+
+module.exports = { transcribeAudio, textToVoice, splitSentences, synthSentenceMp3, TTS_CMD };

package/core/runner.js

@@ -15,8 +15,8 @@ const { currentState, saveState, recordSession, userOwnsClaudeSession, resetSess
 const { chatContext, currentChannelId, currentAdapter } = require("./context");
 const { buildSystemPrompt, promptWithDynamicContext } = require("./system-prompt");
 const { redactSensitive } = require("./redact");
-const { send, editMessage, sendVoice, splitMessage } = require("./io");
-const { textToVoice } = require("./media");
+const { send, editMessage, sendVoice, sendVoiceEnd, splitMessage } = require("./io");
+const { textToVoice, splitSentences, synthSentenceMp3 } = require("./media");
 const { killProcessTree } = require("./process-tree");
 const {
   appendProjectTranscript, transcriptProjectInfo,
@@ -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 {
@@ -857,6 +858,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 +881,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 +907,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 */ }
   };
 
@@ -1200,8 +1217,20 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
         // input is unwanted noise, so gate it to the voice channel.
         const { currentTransport } = require("./context");
         if (currentTransport() === "voice") {
-          const voicePath = await textToVoice(finalText);
-          if (voicePath) await sendVoice(voicePath);
+          // 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) {
+            const voicePath = await textToVoice(finalText);
+            if (voicePath) await sendVoice(voicePath);
+          }
+          await sendVoiceEnd();
         }
       }
     } catch (e) {
@@ -1228,6 +1257,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,
+};