@vellumai/assistant 0.6.4 → 0.6.6

package/src/daemon/message-types/messages.ts

@@ -23,6 +23,10 @@ export interface UserMessage {
   microphonePermissionGranted?: boolean;
   /** Structured command intent — bypasses text parsing when present. */
   commandIntent?: CommandIntent;
+  /** Client-generated correlation nonce for echo dedup. See
+   *  `UserMessageEcho.clientMessageId` — the server echoes this value
+   *  back on the matching `user_message_echo` event. */
+  clientMessageId?: string;
 }
 
 export interface ConfirmationResponse {
@@ -33,7 +37,6 @@ export interface ConfirmationResponse {
     | "allow_10m"
     | "allow_conversation"
     | "always_allow"
-    | "always_allow_high_risk"
     | "deny"
     | "always_deny";
   selectedPattern?: string;
@@ -67,6 +70,11 @@ export interface UserMessageEcho {
   /** Server-generated request ID for the send. Allows correlation with
    *  `message_queued` / `message_dequeued` events for the same turn. */
   requestId?: string;
+  /** Client-generated correlation nonce from the HTTP POST body. Echoed
+   *  back so the originating client can dedupe its optimistic row even
+   *  if the SSE echo beats the 202 response. Absent for synthetic echoes
+   *  (e.g. surface-action prompts) that did not originate from a client POST. */
+  clientMessageId?: string;
 }
 
 export interface AssistantTextDelta {
@@ -137,6 +145,14 @@ export interface ToolResult {
   imageDataList?: string[];
   /** The tool_use block ID for client-side correlation. */
   toolUseId?: string;
+  /** Risk level from the classifier ("low" | "medium" | "high" | "unknown"). */
+  riskLevel?: string;
+  /** Human-readable reason for the risk classification. */
+  riskReason?: string;
+  /** Whether the daemon is running in a containerized (Docker) environment. */
+  isContainerized?: boolean;
+  /** Scope options ladder for the rule editor modal (narrowest to broadest). */
+  riskScopeOptions?: Array<{ pattern: string; label: string }>;
 }
 
 export interface ConfirmationRequest {
@@ -145,6 +161,10 @@ export interface ConfirmationRequest {
   toolName: string;
   input: Record<string, unknown>;
   riskLevel: string;
+  /** Human-readable reason for the risk classification (e.g. "Modifies remote repository state"). */
+  riskReason?: string;
+  /** Whether the daemon is running in a containerized (Docker) environment. */
+  isContainerized?: boolean;
   executionTarget?: "sandbox" | "host";
   allowlistOptions: Array<{
     label: string;

package/src/daemon/message-types/trust.ts

@@ -8,8 +8,6 @@ export interface AddTrustRule {
   pattern: string;
   scope: string;
   decision: "allow" | "deny" | "ask";
-  /** When true, the rule also covers high-risk invocations. */
-  allowHighRisk?: boolean;
   /** Execution target override for this rule. */
   executionTarget?: "host" | "sandbox";
 }

package/src/daemon/parse-actual-tokens-from-error.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
-import { parseActualTokensFromError } from "./conversation-agent-loop.js";
+import { ContextOverflowError } from "../providers/types.js";
+import { parseActualTokensFromError } from "./parse-actual-tokens-from-error.js";
 
 describe("parseActualTokensFromError", () => {
   test("returns null for null input", () => {
@@ -68,4 +69,59 @@ describe("parseActualTokensFromError", () => {
   test("returns null when no numeric pattern matches", () => {
     expect(parseActualTokensFromError("context window exceeded")).toBeNull();
   });
+
+  // ── Typed-error branch ─────────────────────────────────────────────
+
+  test("prefers ContextOverflowError.actualTokens over string-regex match", () => {
+    // Message would regex-parse to 999999, but typed field wins.
+    const err = new ContextOverflowError(
+      "Anthropic API error (400): prompt is too long: 999999 tokens > 200000 maximum",
+      "anthropic",
+      {
+        actualTokens: 242201,
+        maxTokens: 200000,
+      },
+    );
+    expect(parseActualTokensFromError(err)).toBe(242201);
+  });
+
+  test("falls back to regex when ContextOverflowError has no actualTokens", () => {
+    const err = new ContextOverflowError(
+      "OpenAI API error (400): too many input tokens: 150000 > 128000",
+      "openai",
+      {},
+    );
+    expect(parseActualTokensFromError(err)).toBe(150000);
+  });
+
+  test("returns null when ContextOverflowError has neither typed field nor matching message", () => {
+    const err = new ContextOverflowError("context window exceeded", "openai");
+    expect(parseActualTokensFromError(err)).toBeNull();
+  });
+
+  test("typed-error parsing takes precedence over string regex even when both present", () => {
+    // String has 999999 tokens > 200000; typed field says 242201.
+    // The typed field MUST win — this is the core contract.
+    const err = new ContextOverflowError(
+      "prompt is too long: 999999 tokens > 200000 maximum",
+      "anthropic",
+      { actualTokens: 242201 },
+    );
+    expect(parseActualTokensFromError(err)).toBe(242201);
+  });
+
+  test("accepts an untyped Error instance and parses its message", () => {
+    const err = new Error("prompt is too long: 242201 tokens > 200000 maximum");
+    expect(parseActualTokensFromError(err)).toBe(242201);
+  });
+
+  test("ignores non-numeric/invalid actualTokens on typed error", () => {
+    // actualTokens of 0 should fall through (typed check requires > 0).
+    const err = new ContextOverflowError(
+      "prompt is too long: 242201 tokens > 200000 maximum",
+      "anthropic",
+      { actualTokens: 0 },
+    );
+    expect(parseActualTokensFromError(err)).toBe(242201);
+  });
 });

package/src/daemon/parse-actual-tokens-from-error.ts

@@ -0,0 +1,66 @@
+import { isContextOverflowError } from "../providers/types.js";
+
+/**
+ * Parse the actual token count reported by the provider for a
+ * context-too-large failure.
+ *
+ * Prefers the typed `ContextOverflowError.actualTokens` field when the
+ * thrown error is one. Falls back to regex-parsing the message for patterns
+ * like:
+ *   "prompt is too long: 242201 tokens > 200000 maximum"   (Anthropic)
+ *   "too many input tokens: 242201 > 200000"                (OpenAI)
+ *
+ * The regex path remains a safety net for provider-adapter paths (e.g.
+ * managed-proxy rewrappers) that surface untyped errors.
+ *
+ * Accepts a raw error object, an `Error` instance, or a plain string.
+ * Returns the actual token count, or `null` when it cannot be determined.
+ */
+export function parseActualTokensFromError(
+  errorOrMessage: unknown,
+): number | null {
+  // Typed path — the provider client wrapped a matching upstream error as
+  // ContextOverflowError. Use the parsed field directly when available.
+  if (isContextOverflowError(errorOrMessage)) {
+    const actual = errorOrMessage.actualTokens;
+    if (typeof actual === "number" && actual > 0) return actual;
+    // Typed error without `actualTokens` — fall through to regex-parse the
+    // underlying message in case the upstream body carries it in text form.
+    return parseFromMessage(errorOrMessage.message ?? null);
+  }
+
+  // Untyped path — accept either an Error or a string.
+  if (errorOrMessage == null) return null;
+  if (typeof errorOrMessage === "string") {
+    return parseFromMessage(errorOrMessage);
+  }
+  if (typeof errorOrMessage === "object" && "message" in errorOrMessage) {
+    const msg = (errorOrMessage as { message?: unknown }).message;
+    if (typeof msg === "string") return parseFromMessage(msg);
+  }
+  return null;
+}
+
+function parseFromMessage(errorMessage: string | null): number | null {
+  if (!errorMessage) return null;
+
+  // Match patterns like "242201 tokens > 200000" or "242201 > 200000 maximum"
+  const match = errorMessage.match(
+    /(\d[\d,]*)\s*tokens?\s*[>≥]|:\s*(\d[\d,]*)\s*[>≥]/i,
+  );
+  if (match) {
+    const raw = (match[1] || match[2]).replace(/,/g, "");
+    const parsed = parseInt(raw, 10);
+    if (!isNaN(parsed) && parsed > 0) return parsed;
+  }
+
+  // Fallback: match "too many input tokens: N > M"
+  const fallback = errorMessage.match(/(\d[\d,]*)\s*[>≥]\s*\d/);
+  if (fallback) {
+    const raw = fallback[1].replace(/,/g, "");
+    const parsed = parseInt(raw, 10);
+    if (!isNaN(parsed) && parsed > 0) return parsed;
+  }
+
+  return null;
+}

package/src/daemon/pkb-context-tracker.test.ts

@@ -0,0 +1,169 @@
+import path from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import type { ContentBlock, Message } from "../providers/types.js";
+import type { Conversation } from "./conversation.js";
+import { getInContextPkbPaths } from "./pkb-context-tracker.js";
+
+const WORKING_DIR = path.resolve("/tmp/test-pkb-root");
+const PKB_ROOT = path.join(WORKING_DIR, "pkb");
+
+// The helper only reads `conversation.messages`. Constructing a real
+// `Conversation` instance would require a full daemon setup; casting a
+// minimal object through `unknown` keeps the test isolated and pure while
+// still exercising the public type.
+function makeConversation(messages: Message[]): Conversation {
+  return { messages } as unknown as Conversation;
+}
+
+function fileReadToolUse(filePath: string): ContentBlock {
+  return {
+    type: "tool_use",
+    id: `toolu_${Math.random().toString(36).slice(2, 10)}`,
+    name: "file_read",
+    input: { path: filePath },
+  };
+}
+
+function assistantMessageWithBlocks(blocks: ContentBlock[]): Message {
+  return { role: "assistant", content: blocks };
+}
+
+describe("getInContextPkbPaths", () => {
+  test("auto-inject paths are always present (even with empty conversation)", () => {
+    const conversation = makeConversation([]);
+    const result = getInContextPkbPaths(
+      conversation,
+      ["notes/index.md", "journal/2026-04-18.md"],
+      PKB_ROOT,
+      WORKING_DIR,
+    );
+    expect(result).toEqual(
+      new Set([
+        path.join(PKB_ROOT, "notes/index.md"),
+        path.join(PKB_ROOT, "journal/2026-04-18.md"),
+      ]),
+    );
+  });
+
+  test("includes a file_read tool_use with a path inside pkbRoot", () => {
+    const insidePath = path.join(PKB_ROOT, "notes/thoughts.md");
+    const conversation = makeConversation([
+      assistantMessageWithBlocks([fileReadToolUse(insidePath)]),
+    ]);
+    const result = getInContextPkbPaths(conversation, [], PKB_ROOT, WORKING_DIR);
+    expect(result).toEqual(new Set([insidePath]));
+  });
+
+  test("excludes a file_read tool_use whose path is outside pkbRoot", () => {
+    const conversation = makeConversation([
+      assistantMessageWithBlocks([fileReadToolUse("/etc/hosts")]),
+    ]);
+    const result = getInContextPkbPaths(conversation, [], PKB_ROOT, WORKING_DIR);
+    expect(result).toEqual(new Set());
+  });
+
+  test("excludes a non-file_read tool_use with a PKB-like path", () => {
+    const insidePath = path.join(PKB_ROOT, "notes/thoughts.md");
+    const bogus: ContentBlock = {
+      type: "tool_use",
+      id: "toolu_bogus",
+      name: "file_write",
+      input: { path: insidePath },
+    };
+    const conversation = makeConversation([
+      assistantMessageWithBlocks([bogus]),
+    ]);
+    const result = getInContextPkbPaths(conversation, [], PKB_ROOT, WORKING_DIR);
+    expect(result).toEqual(new Set());
+  });
+
+  test("post-compaction context-summary user message returns only auto-inject paths", () => {
+    // After compaction, the structured tool_use blocks have been serialized
+    // away and the conversation is just a user-role text message containing
+    // the summary.
+    const summaryMessage: Message = {
+      role: "user",
+      content: [
+        {
+          type: "text",
+          text: "[Context summary] Previously you read notes/thoughts.md and journal/2026-04-18.md...",
+        },
+      ],
+    };
+    const conversation = makeConversation([summaryMessage]);
+    const autoInject = ["profile/identity.md"];
+    const result = getInContextPkbPaths(
+      conversation,
+      autoInject,
+      PKB_ROOT,
+      WORKING_DIR,
+    );
+    expect(result).toEqual(
+      new Set([path.join(PKB_ROOT, "profile/identity.md")]),
+    );
+  });
+
+  test("path-traversal attempt via ../../etc/passwd is excluded", () => {
+    const conversation = makeConversation([
+      assistantMessageWithBlocks([
+        fileReadToolUse("../../etc/passwd"),
+        fileReadToolUse("notes/../../../etc/shadow"),
+      ]),
+    ]);
+    const result = getInContextPkbPaths(conversation, [], PKB_ROOT, WORKING_DIR);
+    expect(result).toEqual(new Set());
+  });
+
+  test("relative file_read path outside pkbRoot is excluded", () => {
+    // These are resolved against `workingDir` (matching `file_read`'s own
+    // rule), land outside `pkbRoot`, and are correctly ignored.
+    const conversation = makeConversation([
+      assistantMessageWithBlocks([
+        fileReadToolUse("notes.md"),
+        fileReadToolUse("./deep/subdir/file.md"),
+      ]),
+    ]);
+    const result = getInContextPkbPaths(conversation, [], PKB_ROOT, WORKING_DIR);
+    expect(result).toEqual(new Set());
+  });
+
+  test("workspace-relative file_read path inside pkb/ is recognized", () => {
+    // The model emits workspace-relative paths like `pkb/threads.md`.
+    // The tracker resolves them against `workingDir` (matching `file_read`'s
+    // own rule) and verifies the result falls inside `pkbRoot`.
+    const conversation = makeConversation([
+      assistantMessageWithBlocks([fileReadToolUse("pkb/threads.md")]),
+    ]);
+    const result = getInContextPkbPaths(conversation, [], PKB_ROOT, WORKING_DIR);
+    expect(result).toEqual(new Set([path.join(PKB_ROOT, "threads.md")]));
+  });
+
+  test("resolves relative auto-inject paths against pkbRoot", () => {
+    const conversation = makeConversation([]);
+    const result = getInContextPkbPaths(
+      conversation,
+      ["./notes/relative.md"],
+      PKB_ROOT,
+      WORKING_DIR,
+    );
+    expect(result).toEqual(
+      new Set([path.join(PKB_ROOT, "notes/relative.md")]),
+    );
+  });
+
+  test("auto-inject and file_read paths union (no duplicates)", () => {
+    const insidePath = path.join(PKB_ROOT, "notes/shared.md");
+    const conversation = makeConversation([
+      assistantMessageWithBlocks([fileReadToolUse(insidePath)]),
+    ]);
+    const result = getInContextPkbPaths(
+      conversation,
+      ["notes/shared.md"],
+      PKB_ROOT,
+      WORKING_DIR,
+    );
+    expect(result.size).toBe(1);
+    expect(result.has(insidePath)).toBe(true);
+  });
+});

package/src/daemon/pkb-context-tracker.ts

@@ -0,0 +1,125 @@
+/**
+ * pkb-context-tracker
+ *
+ * Pure helper that reports which PKB file paths are already "in context" for
+ * a given conversation. A path is considered in context if either:
+ *
+ *   1. It was explicitly auto-injected (caller supplies `autoInjectPaths`),
+ *      typically via a system-reminder that embeds the file contents.
+ *   2. The conversation history contains a structured `file_read` tool_use
+ *      block whose `input.path` — resolved the same way `file_read` itself
+ *      resolves it (absolute as-is, relative against `workingDir`) — lands
+ *      inside `pkbRoot`.
+ *
+ * Used by the PKB system reminder so we don't suggest files the model has
+ * already loaded.
+ *
+ * Post-compaction note: structured `tool_use` blocks get serialized into a
+ * plain-text summary and dropped from the live message array. After a
+ * compaction, this helper will naturally only see the `autoInjectPaths` —
+ * which is the desired semantics.
+ *
+ * No I/O, no globals, no side effects.
+ */
+
+import path from "node:path";
+
+import type { ContentBlock, Message } from "../providers/types.js";
+
+/**
+ * Minimal shape this helper needs from a `Conversation`. Defining it as an
+ * interface (rather than importing the full `Conversation` class) keeps the
+ * helper pure and trivial to unit-test without constructing a real daemon
+ * conversation.
+ */
+export interface PkbContextConversation {
+  messages: Message[];
+}
+
+/**
+ * The structured tool_use block name the assistant emits when reading files
+ * from the workspace (see `assistant/src/tools/filesystem/read.ts`).
+ */
+const FILE_READ_TOOL_NAME = "file_read";
+
+/**
+ * Resolve `candidate` against `pkbRoot` and return the absolute path ONLY if
+ * it stays inside `pkbRoot`. Otherwise return `undefined`. Guards against
+ * `..`-style path traversal.
+ */
+function resolveInsidePkbRoot(
+  candidate: string,
+  pkbRoot: string,
+): string | undefined {
+  if (typeof candidate !== "string" || candidate.length === 0) {
+    return undefined;
+  }
+  const resolved = path.resolve(pkbRoot, candidate);
+  // `path.resolve` normalizes any `..` segments in `candidate`. We still need
+  // to verify the result is inside `pkbRoot`. Comparing with a trailing
+  // separator avoids treating `<pkbRoot>somethingElse` as inside the root.
+  if (resolved === pkbRoot) {
+    return resolved;
+  }
+  const rootWithSep = pkbRoot.endsWith(path.sep) ? pkbRoot : pkbRoot + path.sep;
+  if (resolved.startsWith(rootWithSep)) {
+    return resolved;
+  }
+  return undefined;
+}
+
+/**
+ * Returns the set of absolute PKB file paths already in the conversation's
+ * in-memory context. This is the union of `autoInjectPaths` (resolved into
+ * `pkbRoot`) and any `file_read` tool_use block inputs found in
+ * `conversation.messages` that resolve inside `pkbRoot`.
+ *
+ * `file_read` resolves its `path` argument against `workingDir` (the tool's
+ * working directory), so this helper mirrors that rule: relative tool paths
+ * are resolved against `workingDir`, absolute paths are taken as-is, and the
+ * resulting absolute path is then accepted only if it falls inside `pkbRoot`.
+ *
+ * Paths outside `pkbRoot` (including `..`-traversal attempts) are excluded.
+ * Tool uses whose `name` is not `file_read` are ignored.
+ */
+export function getInContextPkbPaths(
+  conversation: PkbContextConversation,
+  autoInjectPaths: string[],
+  pkbRoot: string,
+  workingDir: string,
+): Set<string> {
+  const normalizedRoot = path.resolve(pkbRoot);
+  const normalizedWorkingDir = path.resolve(workingDir);
+  const inContext = new Set<string>();
+
+  for (const candidate of autoInjectPaths) {
+    const resolved = resolveInsidePkbRoot(candidate, normalizedRoot);
+    if (resolved !== undefined) {
+      inContext.add(resolved);
+    }
+  }
+
+  for (const message of conversation.messages) {
+    if (!Array.isArray(message.content)) continue;
+    for (const block of message.content as ContentBlock[]) {
+      if (block.type !== "tool_use") continue;
+      if (block.name !== FILE_READ_TOOL_NAME) continue;
+      const rawPath = block.input?.path;
+      if (typeof rawPath !== "string" || rawPath.length === 0) continue;
+      // Mirror `file_read`'s own path resolution: absolute paths are taken
+      // as-is; relative paths resolve against the tool's working directory
+      // (NOT `pkbRoot`). Resolving relative paths against `pkbRoot` would
+      // double-prefix workspace-relative inputs like `pkb/threads.md` into
+      // `<pkbRoot>/pkb/threads.md` and miss the actually-loaded file.
+      const absolute = path.isAbsolute(rawPath)
+        ? path.resolve(rawPath)
+        : path.resolve(normalizedWorkingDir, rawPath);
+      const resolved = resolveInsidePkbRoot(absolute, normalizedRoot);
+      if (resolved !== undefined) {
+        inContext.add(resolved);
+      }
+    }
+  }
+
+  return inContext;
+}

package/src/daemon/pkb-reminder-builder.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "bun:test";
+
+import { buildPkbReminder } from "./pkb-reminder-builder.js";
+
+// Byte-for-byte fixture of the original PKB_SYSTEM_REMINDER from
+// conversation-runtime-assembly.ts. If this ever needs to change, the
+// matching string in conversation-runtime-assembly.ts must change too.
+const ORIGINAL_REMINDER =
+  "<system_reminder>" +
+  "\nRead any unread Personal Knowledge Base files that might be even partially relevant to this conversation" +
+  "\nUse `remember` for anything you learn immediately" +
+  "\n</system_reminder>";
+
+describe("buildPkbReminder", () => {
+  test("empty hints returns exact original reminder byte-for-byte", () => {
+    expect(buildPkbReminder([])).toBe(ORIGINAL_REMINDER);
+  });
+
+  test("single hint renders one bullet with no duplicates or trailing blank line", () => {
+    const out = buildPkbReminder(["projects/alpha.md"]);
+    const expected =
+      "<system_reminder>" +
+      "\nRead any unread Personal Knowledge Base files that might be even partially relevant to this conversation." +
+      "\nBased on the current context, these files look especially relevant:" +
+      "\n- projects/alpha.md" +
+      "\nUse `remember` for anything you learn immediately" +
+      "\n</system_reminder>";
+    expect(out).toBe(expected);
+
+    // Exactly one bullet.
+    const bulletCount = (out.match(/^- /gm) ?? []).length;
+    expect(bulletCount).toBe(1);
+
+    // No blank line before closing tag.
+    expect(out.includes("\n\n</system_reminder>")).toBe(false);
+  });
+
+  test("three hints render all three in order", () => {
+    const hints = ["a.md", "sub/b.md", "c/d/e.md"];
+    const out = buildPkbReminder(hints);
+    const expected =
+      "<system_reminder>" +
+      "\nRead any unread Personal Knowledge Base files that might be even partially relevant to this conversation." +
+      "\nBased on the current context, these files look especially relevant:" +
+      "\n- a.md" +
+      "\n- sub/b.md" +
+      "\n- c/d/e.md" +
+      "\nUse `remember` for anything you learn immediately" +
+      "\n</system_reminder>";
+    expect(out).toBe(expected);
+
+    // Order check — each should appear after the previous.
+    const idxA = out.indexOf("- a.md");
+    const idxB = out.indexOf("- sub/b.md");
+    const idxC = out.indexOf("- c/d/e.md");
+    expect(idxA).toBeGreaterThan(-1);
+    expect(idxB).toBeGreaterThan(idxA);
+    expect(idxC).toBeGreaterThan(idxB);
+  });
+
+  test("hints with special chars (< and &) are emitted verbatim (no escaping)", () => {
+    const hints = ["weird<name>.md", "foo&bar.md"];
+    const out = buildPkbReminder(hints);
+    expect(out).toContain("- weird<name>.md");
+    expect(out).toContain("- foo&bar.md");
+    // Ensure no HTML-style escaping happened.
+    expect(out).not.toContain("&lt;");
+    expect(out).not.toContain("&amp;");
+  });
+});

package/src/daemon/pkb-reminder-builder.ts

@@ -0,0 +1,31 @@
+/**
+ * Render the PKB system_reminder text, optionally with a bulleted list of
+ * hint paths that look especially relevant to the current conversation.
+ *
+ * When `hints` is empty, returns the legacy two-line reminder byte-for-byte.
+ * When `hints` is non-empty, renders an extended reminder with a bullet per
+ * hint. Hints are emitted verbatim — they are trusted internal paths, not
+ * user input, so no escaping is performed.
+ *
+ * Caller is responsible for capping the hints array at 3 entries.
+ */
+export function buildPkbReminder(hints: ReadonlyArray<string>): string {
+  if (hints.length === 0) {
+    return (
+      "<system_reminder>" +
+      "\nRead any unread Personal Knowledge Base files that might be even partially relevant to this conversation" +
+      "\nUse `remember` for anything you learn immediately" +
+      "\n</system_reminder>"
+    );
+  }
+
+  const bullets = hints.map((h) => `- ${h}`).join("\n");
+  return (
+    "<system_reminder>" +
+    "\nRead any unread Personal Knowledge Base files that might be even partially relevant to this conversation." +
+    "\nBased on the current context, these files look especially relevant:" +
+    `\n${bullets}` +
+    "\nUse `remember` for anything you learn immediately" +
+    "\n</system_reminder>"
+  );
+}

package/src/daemon/providers-setup.ts

@@ -27,6 +27,12 @@ import { googleCalendarProvider } from "../watcher/providers/google-calendar.js"
 import { linearProvider } from "../watcher/providers/linear.js";
 import { outlookProvider } from "../watcher/providers/outlook.js";
 import { outlookCalendarProvider } from "../watcher/providers/outlook-calendar.js";
+
+// Side-effect import: runs each bundled first-party skill's tool
+// registration before `initializeTools()` so external tools are visible
+// to the LLM. See `external-skills-bootstrap.ts` for the rationale.
+import "./external-skills-bootstrap.js";
+
 const log = getLogger("lifecycle");
 
 export async function initializeProvidersAndTools(