arisa 5.1.12 → 5.1.24

package/src/runtime/arisa-capabilities.js

@@ -43,6 +43,13 @@ function normalizeLimit(limit) {
   return Math.min(value, 100);
 }
 
+function normalizeAcknowledgement(value) {
+  if (value == null || value === "") return "";
+  const acknowledgement = requireString(value, "acknowledgement").trim();
+  if (acknowledgement.length > 500) throw new Error("acknowledgement must be at most 500 characters");
+  return acknowledgement;
+}
+
 export function createArisaCapabilities({
   artifactStore,
   taskStore,
@@ -206,7 +213,11 @@ export function createArisaCapabilities({
       const resourceId = String(params.resourceId || "").trim();
       return taskStore.add({
         kind: "agent_event",
-        payload: { prompt: requireString(params.prompt, "prompt"), resourceId }
+        payload: {
+          prompt: requireString(params.prompt, "prompt"),
+          resourceId,
+          acknowledgement: normalizeAcknowledgement(params.acknowledgement)
+        }
       }, {
         payload: { chatId: scopedChatId },
         source: { type: "tool", toolName: scopedToolName, chatId: scopedChatId, resourceId }

package/src/runtime/create-app.js

@@ -135,6 +135,7 @@ export async function createApp({ logger, runtimeOverrides, requestRestart } = {
       toolProcessSupervisor,
       daemonPolicy: config.daemons,
       doctorPolicy: config.doctor,
+      inspectToolDependencies: async () => toolRegistry.dependencyIssues(),
       inspectInfrastructure: async () => {
         const tool = toolRegistry.get("master-slave");
         if (!tool) return null;

package/src/runtime/doctor.js

@@ -87,16 +87,43 @@ function daemonLabel(record) {
   return `${record.toolName} (${record.instanceId || "global"})`;
 }
 
-function daemonResultSummary(results) {
-  const states = new Map();
+function daemonState(result) {
+  return result.diagnostic?.state || result.outcome;
+}
+
+function daemonStateLabel(state) {
+  return String(state || "unknown")
+    .split("-")
+    .map((part) => part ? `${part[0].toUpperCase()}${part.slice(1)}` : part)
+    .join(" ");
+}
+
+function daemonReportLines(results) {
+  const priority = ["ready", "starting", "degraded", "unhealthy", "restarting", "stopped", "failed"];
+  const groups = new Map();
   for (const result of results) {
-    const state = result.diagnostic?.state || result.outcome;
-    states.set(state, (states.get(state) || 0) + 1);
+    const state = daemonState(result);
+    if (!groups.has(state)) groups.set(state, []);
+    groups.get(state).push(result);
   }
-  return [...states.entries()]
-    .sort(([left], [right]) => left.localeCompare(right))
-    .map(([state, count]) => `${count} ${state}`)
-    .join(", ");
+  const states = [...groups.keys()].sort((left, right) => {
+    const leftIndex = priority.indexOf(left);
+    const rightIndex = priority.indexOf(right);
+    if (leftIndex === -1 && rightIndex === -1) return left.localeCompare(right);
+    if (leftIndex === -1) return 1;
+    if (rightIndex === -1) return -1;
+    return leftIndex - rightIndex;
+  });
+  const lines = [];
+  for (const state of states) {
+    const group = groups.get(state);
+    lines.push(`  ${daemonStateLabel(state)} (${group.length})`);
+    for (const result of group.sort((left, right) => daemonLabel(left.record).localeCompare(daemonLabel(right.record)))) {
+      const scope = result.record.scope?.type || (result.record.instanceId === "global" ? "global" : "chat");
+      lines.push(...wrapReportText(`${result.record.toolName} [${scope}]`, { firstPrefix: "  - ", nextPrefix: "    " }));
+    }
+  }
+  return lines;
 }
 
 function formatTokenCount(tokens) {
@@ -123,6 +150,24 @@ function formatUptime(seconds) {
   return [days ? `${days}d` : "", hours ? `${hours}h` : "", `${minutes}m`].filter(Boolean).join(" ");
 }
 
+function masterSlaveMode(infrastructure) {
+  const parts = [infrastructure.role || "unknown", infrastructure.daemon?.state || "unknown"];
+  if (infrastructure.paired != null) parts.push(infrastructure.paired ? "paired" : "unpaired");
+  return parts.join(" · ");
+}
+
+function masterSlaveActivity(jobs) {
+  const active = jobs?.active;
+  const queued = jobs?.queued;
+  const failed = jobs?.failed;
+  if ([active, queued, failed].every((value) => value === 0)) return "idle";
+  return `${active ?? "?"} active · ${queued ?? "?"} queued · ${failed ?? "?"} failed`;
+}
+
+function compactEndpoint(endpoint) {
+  return String(endpoint || "not configured").replace(/^tcp:\/\//, "");
+}
+
 export async function inspectSystemResources({ diskPath = arisaHomeDir } = {}) {
   const [load1, load5, load15] = os.loadavg();
   const memoryTotal = os.totalmem();
@@ -221,22 +266,18 @@ export function formatDoctorReport(report) {
   lines.push(...reportRow("Large", large));
   lines.push(...reportRow("Ineff.", inefficient));
   if (measured.length) lines.push(...reportRow("Max", `${Math.max(...measured.map((context) => context.percent)).toFixed(1)}%`));
-  lines.push("", "Daemons");
-  lines.push(...reportRow("Checked", report.daemons.length));
-  if (report.daemons.length) lines.push(...reportRow("Status", daemonResultSummary(report.daemons)));
+  lines.push("", `Daemons (${report.daemons.length})`);
+  if (report.daemons.length) lines.push(...daemonReportLines(report.daemons));
   if (report.infrastructure) {
     lines.push("", "Master/Slave");
     if (report.infrastructure.error) {
       lines.push(...reportRow("Status", `unavailable: ${report.infrastructure.error}`));
     } else {
-      lines.push(...reportRow("Role", report.infrastructure.role || "unknown"));
-      lines.push(...reportRow("Daemon", report.infrastructure.daemon?.state || "unknown"));
-      lines.push(...reportRow("Endpoint", report.infrastructure.endpoint || "not configured"));
-      lines.push(...reportRow("Identity", report.infrastructure.identityFingerprint || "not configured"));
-      lines.push(...reportRow("Paired", report.infrastructure.paired == null ? "n/a" : report.infrastructure.paired ? "yes" : "no"));
+      lines.push(...reportRow("Mode", masterSlaveMode(report.infrastructure)));
+      lines.push(...reportRow("Endpoint", compactEndpoint(report.infrastructure.endpoint)));
+      lines.push(...reportRow("Activity", masterSlaveActivity(report.infrastructure.jobs)));
       lines.push(...reportRow("Tools", report.infrastructure.toolCount ?? "unknown"));
-      lines.push(...reportRow("Jobs", `active=${report.infrastructure.jobs?.active ?? "unknown"}, queued=${report.infrastructure.jobs?.queued ?? "unknown"}, failed=${report.infrastructure.jobs?.failed ?? "unknown"}`));
-      lines.push(...reportRow("Pending secrets", report.infrastructure.pendingSecrets ?? "unknown"));
+      lines.push(...reportRow("Secrets", `${report.infrastructure.pendingSecrets ?? "unknown"} pending`));
     }
   }
   if (report.system) {
@@ -273,7 +314,8 @@ export async function runDoctor({
   stopDaemon = stopManagedDaemon,
   unregisterDaemon = unregisterManagedDaemon,
   inspectResources = inspectSystemResources,
-  inspectInfrastructure = null
+  inspectInfrastructure = null,
+  inspectToolDependencies = null
 }) {
   assertDoctorPolicy(doctorPolicy);
   const runtime = await agentManager.getRuntimeDiagnostic({
@@ -290,6 +332,16 @@ export async function runDoctor({
     infrastructure: null
   };
   addContextAttention(report);
+  if (inspectToolDependencies) {
+    try {
+      for (const issue of await inspectToolDependencies()) {
+        const installed = issue.installedVersion ? `; installed ${issue.installedVersion}` : "";
+        report.attention.push(`Tool dependency ${issue.type}: ${issue.tool} requires ${issue.dependency}@${issue.range || "valid"}${installed}.`);
+      }
+    } catch (error) {
+      report.attention.push(`Tool dependency inspection failed: ${error?.message || error}`);
+    }
+  }
   if (inspectInfrastructure) {
     try {
       report.infrastructure = await inspectInfrastructure();

package/src/runtime/tool-usage-report.js

@@ -1,18 +1,33 @@
 import { renderTextReport } from "./report-format.js";
 
-export function formatToolUsageReport(tools) {
-  const lines = ["Arisa tools", "===========", "Usage count"];
-  if (!tools.length) lines.push("  (none installed)");
-
-  const sortedTools = [...tools].sort((left, right) =>
+function sortedTools(tools) {
+  return [...tools].sort((left, right) =>
     Number(right.count) - Number(left.count) || String(left.name).localeCompare(String(right.name))
   );
-  const nameWidth = Math.max(0, ...sortedTools.map((tool) => String(tool.name).length));
-  const countWidth = Math.max(1, ...sortedTools.map((tool) => String(tool.count).length));
-  for (const tool of sortedTools) {
+}
+
+function usageRows(tools, nameWidth, countWidth) {
+  if (!tools.length) return ["  (none)"];
+  return sortedTools(tools).map((tool) => {
     const name = String(tool.name).padEnd(nameWidth);
     const count = String(tool.count).padStart(countWidth);
-    lines.push(`- ${name}  ${count}`);
-  }
+    return `- ${name}  ${count}`;
+  });
+}
+
+export function formatToolUsageReport(tools) {
+  const official = tools.filter((tool) => tool.official);
+  const local = tools.filter((tool) => !tool.official);
+  const nameWidth = Math.max(0, ...tools.map((tool) => String(tool.name).length));
+  const countWidth = Math.max(1, ...tools.map((tool) => String(tool.count).length));
+  const lines = [
+    "Arisa tools",
+    "===========",
+    "Official",
+    ...usageRows(official, nameWidth, countWidth),
+    "",
+    "Local",
+    ...usageRows(local, nameWidth, countWidth)
+  ];
   return renderTextReport(lines);
 }

package/src/transport/telegram/bot.js

@@ -354,21 +354,23 @@ function buildStartupMessage(chatMeta = {}) {
 }
 
 export async function collectText(session, prompt, { logger, chatId, onSlowPrompt } = {}) {
-  let text = "";
+  const assistantMessages = [];
+  let assistantMessage = "";
   let assistantErrorMessage = "";
-  let shouldSeparateAssistantMessage = false;
   let slowPromptTimer = null;
+  const finishAssistantMessage = () => {
+    if (assistantMessage && !isSilentReply(assistantMessage)) {
+      assistantMessages.push(assistantMessage);
+    }
+    assistantMessage = "";
+  };
   const unsubscribe = session.subscribe((event) => {
     if (event.arisaPromptScoped === false) return;
     if (event.type === "message_start" && event.message.role === "assistant") {
-      shouldSeparateAssistantMessage = text.trim().length > 0;
+      finishAssistantMessage();
     }
     if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
-      if (shouldSeparateAssistantMessage && event.assistantMessageEvent.delta) {
-        text += "\n\n";
-        shouldSeparateAssistantMessage = false;
-      }
-      text += event.assistantMessageEvent.delta;
+      assistantMessage += event.assistantMessageEvent.delta;
     }
     if (event.type === "message_end" && event.message?.role === "assistant") {
       if (event.message.stopReason === "error") {
@@ -377,6 +379,7 @@ export async function collectText(session, prompt, { logger, chatId, onSlowPromp
         // Auto-compaction and retry can emit a transient error before a successful continuation.
         assistantErrorMessage = "";
       }
+      finishAssistantMessage();
     }
     const logMessage = sessionEventLogMessage(event);
     if (logMessage) logger?.log("agent", `chat ${chatId} ${logMessage}`);
@@ -402,7 +405,8 @@ export async function collectText(session, prompt, { logger, chatId, onSlowPromp
     throw new Error(assistantErrorMessage);
   }
 
-  return text.trim();
+  finishAssistantMessage();
+  return assistantMessages.join("\n\n").trim();
 }
 
 export function isSilentReply(text) {
@@ -431,16 +435,30 @@ function sanitizeSessionHandoff(text) {
   return `${sanitized.slice(0, 3997).trim()}...`;
 }
 
-async function withTyping(ctx, work) {
-  await ctx.api.sendChatAction(ctx.chat.id, "typing");
+export async function startTelegramTyping(ctx) {
+  await ctx.api.sendChatAction(ctx.chat.id, "typing").catch(() => {});
   const timer = setInterval(() => {
     ctx.api.sendChatAction(ctx.chat.id, "typing").catch(() => {});
   }, 4000);
+  return () => clearInterval(timer);
+}
+
+export async function ensureQueuedTelegramTyping(chatState, ctx) {
+  if (chatState.stopQueuedTyping) return;
+  chatState.stopQueuedTyping = await startTelegramTyping(ctx);
+}
+
+export function stopQueuedTelegramTyping(chatState) {
+  chatState.stopQueuedTyping?.();
+  chatState.stopQueuedTyping = null;
+}
 
+async function withTyping(ctx, work) {
+  const stopTyping = await startTelegramTyping(ctx);
   try {
     return await work();
   } finally {
-    clearInterval(timer);
+    stopTyping();
   }
 }
 
@@ -456,7 +474,8 @@ export function createChatStateStore() {
       beforeNextPrompt: null,
       activeSession: null,
       activeSteers: [],
-      assistantMessages: new Map()
+      assistantMessages: new Map(),
+      stopQueuedTyping: null
     };
     states.set(String(chatId), state);
     return state;
@@ -555,6 +574,7 @@ export async function drainChatPromptQueue({
       chatState.continueAfterClose = false;
     }
   } finally {
+    stopQueuedTelegramTyping(chatState);
     chatState.processing = false;
     chatState.activeSession = null;
     chatState.activeSteers = [];
@@ -1065,6 +1085,7 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, t
     const chatState = getChatState(ctx.chat.id);
 
     if (chatState.processing) {
+      await ensureQueuedTelegramTyping(chatState, ctx);
       const incomingPrompt = await buildIncomingPrompt(ctx);
       const busyMessageMode = typeof ctx.message?.text === "string"
         ? resolveTelegramBusyMessageMode(config, ctx.chat.id)
@@ -1111,6 +1132,13 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, t
     timer.unref?.();
   }
 
+  async function enqueueAsyncPrompt({ chatId, prompt, label }) {
+    const ctx = { chat: { id: chatId }, api: bot.api };
+    const chatState = getChatState(chatId);
+    if (chatState.processing) await ensureQueuedTelegramTyping(chatState, ctx);
+    return enqueuePrompt({ chatId, prompt, label, ctx });
+  }
+
   async function dispatchTask(task) {
     const chatId = task.payload?.chatId;
     if (!chatId) {
@@ -1124,7 +1152,7 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, t
         return;
       }
       logger?.log("tasks", `running task ${task.id} for chat ${chatId}`);
-      await enqueuePrompt({
+      await enqueueAsyncPrompt({
         chatId,
         prompt: await buildAsyncTaskPrompt({ task, artifactStore, toolRegistry, resourceNotes, logger }),
         label: `scheduled task ${task.id}`
@@ -1135,7 +1163,15 @@ export async function createTelegramBot({ config, artifactStore, toolRegistry, t
 
     if (task.kind === "agent_event") {
       logger?.log("tasks", `agent event ${task.id} for chat ${chatId}`);
-      await enqueuePrompt({
+      const acknowledgement = String(task.payload?.acknowledgement || "").trim();
+      if (acknowledgement) {
+        try {
+          await bot.api.sendMessage(chatId, acknowledgement);
+        } catch (error) {
+          logger?.log("telegram", `agent event acknowledgement failed for chat ${chatId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+      await enqueueAsyncPrompt({
         chatId,
         prompt: await buildAsyncEventPrompt(task, resourceNotes),
         label: `agent event ${task.id}`

package/test/capabilities-security.test.js

@@ -142,6 +142,27 @@ test("requires chatId for chat-scoped IPC methods", async () => {
   }
 });
 
+test("agent events preserve a bounded immediate acknowledgement", async () => {
+  const capabilities = createCapabilities();
+  const created = await capabilities.dispatch({
+    method: "agent.enqueueEvent",
+    toolName: "browser-session-bridge",
+    chatId: "chat-a",
+    params: {
+      prompt: "Continue the pending authorization flow",
+      acknowledgement: "Authorization received. Continuing now."
+    }
+  });
+
+  assert.equal(created.payload.acknowledgement, "Authorization received. Continuing now.");
+  await assert.rejects(() => capabilities.dispatch({
+    method: "agent.enqueueEvent",
+    toolName: "browser-session-bridge",
+    chatId: "chat-a",
+    params: { prompt: "Continue", acknowledgement: "x".repeat(501) }
+  }), /at most 500 characters/);
+});
+
 test("delivers only artifacts resolved from the requesting chat", async () => {
   const artifact = { id: "artifact-1", chatId: "chat-a", path: "/safe/chat-a/file.txt" };
   const deliveries = [];

package/test/context-and-task-bounds.test.js

@@ -4,13 +4,38 @@ import {
   collectText,
   createChatStateStore,
   drainChatPromptQueue,
+  ensureQueuedTelegramTyping,
   isSilentReply,
   queueChatPrompt,
   resolveTelegramBusyMessageMode,
-  routeBusyPrompt
+  routeBusyPrompt,
+  stopQueuedTelegramTyping
 } from "../src/transport/telegram/bot.js";
 import { selectScheduledTasks } from "../src/core/agent/agent-manager.js";
 
+test("queued Telegram prompts start typing immediately and share one indicator", async () => {
+  let actions = 0;
+  const chatState = { stopQueuedTyping: null };
+  const ctx = {
+    chat: { id: 879964957 },
+    api: {
+      async sendChatAction(chatId, action) {
+        assert.equal(chatId, 879964957);
+        assert.equal(action, "typing");
+        actions += 1;
+      }
+    }
+  };
+
+  await ensureQueuedTelegramTyping(chatState, ctx);
+  await ensureQueuedTelegramTyping(chatState, ctx);
+  assert.equal(actions, 1);
+  assert.equal(typeof chatState.stopQueuedTyping, "function");
+
+  stopQueuedTelegramTyping(chatState);
+  assert.equal(chatState.stopQueuedTyping, null);
+});
+
 function createSession(events) {
   const listeners = new Set();
   return {
@@ -59,6 +84,44 @@ test("collectText preserves the final assistant error", async () => {
   await assert.rejects(() => collectText(session, "hello"), /terminal failure/);
 });
 
+test("collectText drops a standalone silent event reply before a steered response", async () => {
+  const session = createSession([
+    { type: "message_start", message: { role: "assistant" } },
+    {
+      type: "message_update",
+      message: { role: "assistant" },
+      assistantMessageEvent: { type: "text_delta", delta: "NO_REPLY" }
+    },
+    { type: "message_end", message: { role: "assistant", stopReason: "stop" } },
+    { type: "message_start", message: { role: "assistant" } },
+    {
+      type: "message_update",
+      message: { role: "assistant" },
+      assistantMessageEvent: { type: "text_delta", delta: "The useful Telegram response." }
+    },
+    { type: "message_end", message: { role: "assistant", stopReason: "stop" } }
+  ]);
+
+  assert.equal(await collectText(session, "event followed by a Telegram steer"), "The useful Telegram response.");
+});
+
+test("collectText preserves useful text in the same message as a silent marker", async () => {
+  const session = createSession([
+    { type: "message_start", message: { role: "assistant" } },
+    {
+      type: "message_update",
+      message: { role: "assistant" },
+      assistantMessageEvent: { type: "text_delta", delta: "NO_REPLY\n\nThis text belongs to the same response." }
+    },
+    { type: "message_end", message: { role: "assistant", stopReason: "stop" } }
+  ]);
+
+  assert.equal(
+    await collectText(session, "one response that mentions the marker"),
+    "NO_REPLY\n\nThis text belongs to the same response."
+  );
+});
+
 test("recognizes standalone silent reply markers", () => {
   assert.equal(isSilentReply("NO_REPLY"), true);
   assert.equal(isSilentReply("No reply needed."), true);
@@ -96,7 +159,8 @@ test("chat state uses one queue for numeric and string chat IDs", () => {
     beforeNextPrompt: null,
     activeSession: null,
     activeSteers: [],
-    assistantMessages: new Map()
+    assistantMessages: new Map(),
+    stopQueuedTyping: null
   });
 });
 

package/test/doctor.test.js

@@ -87,6 +87,61 @@ test("reports Pi context size and retained-content inefficiency", async () => {
   assert.ok(formatted.split("\n").every((line) => [...line].length <= 35));
 });
 
+test("lists each checked daemon with its scope and state", async () => {
+  const { report } = await run({
+    repairs: [
+      {
+        record: { toolName: "master-slave", instanceId: "global", scope: { type: "global" } },
+        diagnostic: { state: "ready" },
+        outcome: "healthy"
+      },
+      {
+        record: { toolName: "context-vault", instanceId: "chat-1", scope: { type: "chat" } },
+        diagnostic: { state: "stopped" },
+        outcome: "stopped"
+      }
+    ]
+  });
+
+  report.infrastructure = {
+    role: "master",
+    daemon: { state: "ready" },
+    endpoint: "tcp://198.74.61.48:4719",
+    paired: null,
+    identityFingerprint: "unnecessarily-long-fingerprint",
+    toolCount: 0,
+    jobs: { active: 0, queued: 0, failed: 0 },
+    pendingSecrets: 0
+  };
+  const formatted = formatDoctorReport(report);
+  assert.match(formatted, /Daemons \(2\)\n  Ready \(1\)\n  - master-slave \[global\]/);
+  assert.match(formatted, /  Stopped \(1\)\n  - context-vault \[chat\]/);
+  assert.match(formatted, /Master\/Slave\n  Mode       master · ready/);
+  assert.match(formatted, /Endpoint   198\.74\.61\.48:4719/);
+  assert.match(formatted, /Activity   idle/);
+  assert.doesNotMatch(formatted, /Identity|fingerprint|Paired/);
+  assert.ok(formatted.split("\n").every((line) => [...line].length <= 35));
+});
+
+test("reports missing tool dependencies as attention items", async () => {
+  const report = await runDoctor({
+    agentManager: { getRuntimeDiagnostic: async () => runtime() },
+    toolProcessSupervisor: { repair: async () => [] },
+    daemonPolicy,
+    doctorPolicy,
+    listProcesses: async () => [],
+    serviceStatus: async () => ({ running: false }),
+    inspectResources: async () => system,
+    inspectToolDependencies: async () => [{
+      tool: "magnific-mcp",
+      type: "missing",
+      dependency: "mcp-client",
+      range: "^0.1.0"
+    }]
+  });
+  assert.match(report.attention.join("\n"), /magnific-mcp requires mcp-client@\^0\.1\.0/);
+});
+
 test("stops only a registered duplicate Arisa service with verified identity", async () => {
   const duplicatePid = 321;
   const { report, stopped } = await run({

package/test/official-tool-dependencies.test.js

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+
+async function manifest(name) {
+  return JSON.parse(await readFile(new URL(`../../tools/${name}/tool.manifest.json`, import.meta.url), "utf8"));
+}
+
+test("official orchestrators declare their hard tool dependencies", async () => {
+  assert.deepEqual((await manifest("magnific-mcp")).toolDependencies, { "mcp-client": "^0.1.0" });
+  assert.deepEqual((await manifest("campaign-draft-runner")).toolDependencies, {
+    "pr-campaign": "^0.1.0",
+    "gmail-workspace": "^0.1.0"
+  });
+  assert.deepEqual((await manifest("x-campaign-runner")).toolDependencies, { "x-dm": "^0.2.0" });
+  assert.deepEqual((await manifest("official-tool-sync")).toolDependencies, { trash: "^1.0.0" });
+});
+
+test("optional tool integrations do not become hard dependencies", async () => {
+  assert.deepEqual((await manifest("whatsapp-web")).toolDependencies, undefined);
+  assert.deepEqual((await manifest("pr-campaign")).toolDependencies, undefined);
+  assert.deepEqual((await manifest("master-slave")).toolDependencies, undefined);
+});

package/test/official-tool-installer.test.js

@@ -3,6 +3,7 @@ import crypto from "node:crypto";
 import { cp, mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import test from "node:test";
 import {
   installBundledOfficialTool,
@@ -59,6 +60,18 @@ test("verifies the exact file set and digests", async (t) => {
   await assert.rejects(() => verifyOfficialToolTree(source, files), /unexpected=extra.js/);
 });
 
+test("every bundled official tool lock matches the catalog source", async () => {
+  const lock = JSON.parse(await readFile(new URL("../src/official-tools.lock.json", import.meta.url), "utf8"));
+  for (const [name, entry] of Object.entries(lock.tools)) {
+    const source = fileURLToPath(new URL(`../../tools/${name}/`, import.meta.url));
+    assert.deepEqual(
+      await verifyOfficialToolTree(source, entry.files),
+      { files: Object.keys(entry.files).length },
+      name
+    );
+  }
+});
+
 test("rejects symbolic links before deployment", async (t) => {
   const { source, files } = await fixture(t);
   await symlink(path.join(source, "index.js"), path.join(source, "link.js"));
@@ -72,15 +85,18 @@ test("installs a verified staged tree without overwriting an existing tool", asy
     await mkdir(path.join(checkoutDir, "tools"), { recursive: true });
     await cp(source, path.join(checkoutDir, "tools", "master-slave"), { recursive: true });
   };
+  const lifecycle = [];
   const result = await installLockedOfficialTool({
     toolName: "master-slave",
     lock: lock(files),
     destination,
     scratchRoot: root,
     checkout,
-    validate: async () => {}
+    installDependencies: async () => { lifecycle.push("dependencies"); },
+    validate: async () => { lifecycle.push("validate"); }
   });
   assert.equal(result.commit, "a".repeat(40));
+  assert.deepEqual(lifecycle, ["dependencies", "validate"]);
   assert.equal(await readFile(path.join(destination, "index.js"), "utf8"), "process.stdout.write('ok');\n");
   await assert.rejects(
     () => installLockedOfficialTool({ toolName: "master-slave", lock: lock(files), destination, scratchRoot: root, checkout }),
@@ -100,8 +116,31 @@ test("loads the bundled lock before selecting the canonical tool destination", a
       return { installed: true };
     }
   });
-  assert.deepEqual(result, { installed: true });
+  assert.deepEqual(result, { installed: true, dependencies: [] });
   assert.equal(calls[0].toolName, "master-slave");
   assert.deepEqual(calls[0].lock, lock(files));
   assert.match(calls[0].destination, /tools\/master-slave$/);
 });
+
+test("installs locked tool dependencies before the requested tool", async (t) => {
+  const { root, files } = await fixture(t);
+  const dependencyLock = lock(files);
+  dependencyLock.tools = {
+    "mcp-client": { version: "0.1.0", toolDependencies: {}, files },
+    "magnific-mcp": { version: "0.1.0", toolDependencies: { "mcp-client": "^0.1.0" }, files }
+  };
+  const lockFile = path.join(root, "dependency-lock.json");
+  await writeFile(lockFile, `${JSON.stringify(dependencyLock)}\n`);
+  const calls = [];
+  const result = await installBundledOfficialTool("magnific-mcp", {
+    lockFile,
+    resolveInstalledVersion: async () => undefined,
+    install: async ({ toolName }) => {
+      calls.push(toolName);
+      return { toolName, installed: true };
+    }
+  });
+  assert.deepEqual(calls, ["mcp-client", "magnific-mcp"]);
+  assert.equal(result.toolName, "magnific-mcp");
+  assert.deepEqual(result.dependencies, [{ name: "mcp-client", version: "0.1.0", status: "installed" }]);
+});