@vellumai/assistant 0.7.3 → 0.8.0

package/ARCHITECTURE.md

@@ -1278,7 +1278,7 @@ graph TB
 - Managed-store writes are atomic (tmp file + rename) to prevent partial `SKILL.md` or `SKILLS.md` files.
 - After persist or delete, the file watcher triggers conversation eviction; the next turn runs in a fresh conversation. The model's system prompt instructs it to continue normally.
 - macOS UI shows Inspect and Delete controls for managed skills only (source = "managed").
-- `skill_load` validates the recursive include graph (via `include-graph.ts`) before emitting output. Missing children and cycles produce `isError: true` with no `<loaded_skill>` marker. Valid includes produce an "Included Skills (immediate)" metadata section showing child ID, name, description, and path.
+- `skill_load` resolves the recursive include graph (via `include-graph.ts`) before emitting output. Missing children are listed as suggested skills without child `<loaded_skill>` markers; cycles still produce `isError: true` with no marker. Valid includes produce an "Included Skills (immediate)" metadata section showing child ID, name, description, and path.
 
 ### Skills Authoring via HTTP
 
@@ -1289,32 +1289,33 @@ The Skills page in the macOS client can author managed skills through the daemon
 
 ### Include Graph Validation
 
-Skills can declare child relationships via the `includes` frontmatter field (a JSON array of skill IDs). When `skill_load` loads a parent skill, it validates the full recursive include graph before emitting output.
+Skills can declare child relationships via the `includes` frontmatter field (a JSON array of skill IDs). When `skill_load` loads a parent skill, it attempts to resolve and auto-install missing includes before emitting output. Available includes are appended to the loaded skill output; unavailable includes are surfaced as suggestions instead of blocking the parent skill.
 
 ```mermaid
 graph LR
     LOAD["skill_load(parent)"] --> CATALOG["loadSkillCatalog()"]
     CATALOG --> INDEX["indexCatalogById()"]
-    INDEX --> VALIDATE["validateIncludes(rootId, index)"]
-    VALIDATE -->|"ok"| OUTPUT["Emit output +<br/>Included Skills (immediate)<br/>+ loaded_skill marker"]
-    VALIDATE -->|"missing child"| ERR_MISSING["isError: true<br/>no loaded_skill marker"]
-    VALIDATE -->|"cycle detected"| ERR_CYCLE["isError: true<br/>no loaded_skill marker"]
+    INDEX --> AUTOINSTALL["Attempt catalog auto-install<br/>for missing includes"]
+    AUTOINSTALL --> RESOLVE["collectAllMissing(rootId, index)<br/>+ validateIncludeCycles(rootId, index)"]
+    RESOLVE -->|"ok + no missing child"| OUTPUT["Emit output +<br/>Included Skills (immediate)<br/>+ loaded_skill markers"]
+    RESOLVE -->|"ok + missing child"| OUTPUT_MISSING["Emit parent output +<br/>Suggested Included Skills<br/>without child markers"]
+    RESOLVE -->|"cycle detected"| ERR_CYCLE["isError: true<br/>no loaded_skill marker"]
 ```
 
 **Validation rules:**
 
-- **Missing children**: If any skill in the recursive graph references an `includes` ID not found in the catalog, validation fails with the full path from root to the missing reference.
+- **Missing children**: Missing includes trigger catalog auto-install attempts. Any include still unavailable is listed under "Suggested Included Skills (not loaded)" and does not receive a `<loaded_skill>` marker.
 - **Cycles**: Three-state DFS (unseen → visiting → done) detects direct and indirect cycles. The error includes the cycle path.
-- **Fail-closed**: On any validation error, `skill_load` returns `isError: true` with no `<loaded_skill>` marker, preventing the agent from using a skill with broken dependencies.
+- **Fail-closed cycles**: Circular include chains still return `isError: true` with no `<loaded_skill>` marker.
 
-**Key constraint**: Include metadata is metadata-only. Child skills are **not** auto-activated — the agent must explicitly call `skill_load` for each child. The `projectSkillTools()` function only projects tools for skills with explicit `<loaded_skill>` markers in conversation history.
+**Key constraint**: Include metadata is advisory. Available included skills are appended to the parent output and receive explicit `<loaded_skill>` markers; unavailable included skills remain suggestions so the agent can search for and install them if the task needs their guidance or tools.
 
-| Source File                             | Purpose                                                                                    |
-| --------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `assistant/src/skills/include-graph.ts` | `indexCatalogById()`, `getImmediateChildren()`, `validateIncludes()`, `traverseIncludes()` |
-| `assistant/src/tools/skills/load.ts`    | Include validation integration in `skill_load` execute path                                |
-| `assistant/src/config/skills.ts`        | `includes` field parsing from SKILL.md frontmatter                                         |
-| `assistant/src/skills/managed-store.ts` | `includes` emission in `buildSkillMarkdown()`                                              |
+| Source File                             | Purpose                                                                                                               |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `assistant/src/skills/include-graph.ts` | `indexCatalogById()`, `getImmediateChildren()`, `validateIncludes()`, `validateIncludeCycles()`, `traverseIncludes()` |
+| `assistant/src/tools/skills/load.ts`    | Include resolution integration in `skill_load` execute path                                                           |
+| `assistant/src/config/skills.ts`        | `includes` field parsing from SKILL.md frontmatter                                                                    |
+| `assistant/src/skills/managed-store.ts` | `includes` emission in `buildSkillMarkdown()`                                                                         |
 
 ---
 
@@ -1553,19 +1554,19 @@ Every layer in the pipeline defaults to rejection rather than silent degradation
 
 ### Key Source Files
 
-| File                                                | Role                                                                                       |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `assistant/src/config/skills.ts`                    | Skill catalog loading: bundled, managed, workspace, extra directories                      |
-| `assistant/src/config/bundled-skills/`              | Bundled skill directories (browser, gmail, computer-use, weather, etc.)                    |
-| `assistant/src/skills/tool-manifest.ts`             | `TOOLS.json` parser and validator                                                          |
-| `assistant/src/skills/active-skill-tools.ts`        | `deriveActiveSkills()` — scans history for `<loaded_skill>` markers                        |
-| `assistant/src/skills/include-graph.ts`             | Include graph builder: `indexCatalogById()`, `validateIncludes()`, cycle/missing detection |
-| `assistant/src/daemon/conversation-skill-tools.ts`  | `projectSkillTools()` — per-turn projection, register/unregister lifecycle                 |
-| `assistant/src/tools/skills/skill-tool-factory.ts`  | `createSkillToolsFromManifest()` — manifest entries to Tool objects                        |
-| `assistant/src/tools/skills/skill-script-runner.ts` | Host runner: dynamic import + `run()` call                                                 |
-| `assistant/src/tools/skills/sandbox-runner.ts`      | Sandbox runner: isolated subprocess execution                                              |
-| `assistant/src/tools/registry.ts`                   | `registerSkillTools()` / `unregisterSkillTools()` — global tool registry                   |
-| `assistant/src/permissions/checker.ts`              | Skill-origin default-ask permission policy                                                 |
+| File                                                | Role                                                                                         |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `assistant/src/config/skills.ts`                    | Skill catalog loading: bundled, managed, workspace, extra directories                        |
+| `assistant/src/config/bundled-skills/`              | Bundled skill directories (browser, gmail, computer-use, weather, etc.)                      |
+| `assistant/src/skills/tool-manifest.ts`             | `TOOLS.json` parser and validator                                                            |
+| `assistant/src/skills/active-skill-tools.ts`        | `deriveActiveSkills()` — scans history for `<loaded_skill>` markers                          |
+| `assistant/src/skills/include-graph.ts`             | Include graph builder: `indexCatalogById()`, `validateIncludes()`, `validateIncludeCycles()` |
+| `assistant/src/daemon/conversation-skill-tools.ts`  | `projectSkillTools()` — per-turn projection, register/unregister lifecycle                   |
+| `assistant/src/tools/skills/skill-tool-factory.ts`  | `createSkillToolsFromManifest()` — manifest entries to Tool objects                          |
+| `assistant/src/tools/skills/skill-script-runner.ts` | Host runner: dynamic import + `run()` call                                                   |
+| `assistant/src/tools/skills/sandbox-runner.ts`      | Sandbox runner: isolated subprocess execution                                                |
+| `assistant/src/tools/registry.ts`                   | `registerSkillTools()` / `unregisterSkillTools()` — global tool registry                     |
+| `assistant/src/permissions/checker.ts`              | Skill-origin default-ask permission policy                                                   |
 
 ---
 

package/Dockerfile

@@ -22,6 +22,7 @@ COPY packages/service-contracts ./packages/service-contracts
 COPY packages/credential-storage ./packages/credential-storage
 COPY packages/egress-proxy ./packages/egress-proxy
 COPY packages/gateway-client ./packages/gateway-client
+COPY packages/ipc-server-utils ./packages/ipc-server-utils
 COPY packages/skill-host-contracts ./packages/skill-host-contracts
 COPY packages/slack-text ./packages/slack-text
 COPY packages/twilio-client ./packages/twilio-client

package/__tests__/permissions/gateway-threshold-reader.test.ts

@@ -31,18 +31,70 @@ mock.module("../../src/ipc/gateway-client.js", () => ({
   },
 }));
 
-// Suppress logger output in tests
-mock.module("../../src/util/logger.js", () => ({
-  getLogger: () => ({
-    warn: () => {},
-    info: () => {},
-    error: () => {},
-    debug: () => {},
-  }),
-}));
+// Capture logger output so coalescing tests can assert on it. Existing
+// tests don't read the array, so capturing is invisible to them.
+//
+// Bun's `mock.module("../../src/util/logger.js", ...)` does not intercept
+// transitive imports (see comment in stt-hints.test.ts and avatar-e2e.test.ts).
+// Mocking `pino` at the package level works because getLogger uses pino
+// child loggers under the hood — intercepting pino captures everything.
+interface LogCall {
+  level: "warn" | "info" | "error" | "debug";
+  fields: Record<string, unknown>;
+  message: string;
+}
+const logCalls: LogCall[] = [];
+
+function makeLogFn(level: LogCall["level"]) {
+  return (
+    fieldsOrMsg: Record<string, unknown> | string,
+    maybeMsg?: string,
+  ) => {
+    if (typeof fieldsOrMsg === "string") {
+      logCalls.push({ level, fields: {}, message: fieldsOrMsg });
+    } else {
+      logCalls.push({
+        level,
+        fields: fieldsOrMsg,
+        message: maybeMsg ?? "",
+      });
+    }
+  };
+}
+
+const mockChildLogger = {
+  debug: () => {},
+  info: makeLogFn("info"),
+  warn: makeLogFn("warn"),
+  error: makeLogFn("error"),
+  fatal: () => {},
+  trace: () => {},
+  silent: () => {},
+  // pino loggers are themselves callable as a no-op shorthand; child() returns
+  // another logger.
+  child(): typeof mockChildLogger {
+    return mockChildLogger;
+  },
+  bindings: () => ({}),
+  level: "info",
+};
+
+const mockPinoLogger = Object.assign(() => mockChildLogger, {
+  destination: () => ({}),
+  multistream: () => ({}),
+  stdTimeFunctions: { isoTime: () => "" },
+  stdSerializers: {},
+  symbols: {},
+});
+
+mock.module("pino", () => ({ default: mockPinoLogger }));
+mock.module("pino-pretty", () => ({ default: () => ({}) }));
 
 import {
   _clearGlobalCacheForTesting,
+  _getFailureStateForTesting,
+  _resetFailureCoalesceForTesting,
+  _setFailureWarnIntervalForTesting,
   getAutoApproveThreshold,
 } from "../../src/permissions/gateway-threshold-reader.js";
 
@@ -51,7 +103,9 @@ import {
 function resetMocks(): void {
   ipcCallLog.length = 0;
   ipcHandler = () => undefined;
+  logCalls.length = 0;
   _clearGlobalCacheForTesting();
+  _resetFailureCoalesceForTesting();
 }
 
 afterEach(resetMocks);
@@ -221,3 +275,176 @@ describe("getAutoApproveThreshold", () => {
     expect(ipcCallLog).toEqual(["/v1/permissions/thresholds"]);
   });
 });
+
+// ── Failure coalescing ───────────────────────────────────────────────────────
+
+describe("failure-coalescing log behavior", () => {
+  test("first failure WARNs immediately and starts a streak", async () => {
+    ipcHandler = () => {
+      throw new Error("Connection refused");
+    };
+
+    expect(await getAutoApproveThreshold(undefined, "background")).toBe("none");
+
+    const warns = logCalls.filter((c) => c.level === "warn");
+    expect(warns.length).toBe(1);
+    expect(warns[0]?.fields).toMatchObject({
+      op: "global_thresholds",
+      consecutiveFailures: 1,
+      event: "ipc_threshold_failure",
+    });
+
+    const state = _getFailureStateForTesting("global_thresholds");
+    expect(state).toBeDefined();
+    expect(state?.consecutiveFailures).toBe(1);
+  });
+
+  test("subsequent failures within the WARN window do not log but still increment state", async () => {
+    // 1-hour window so the test never accidentally crosses it.
+    _setFailureWarnIntervalForTesting(60 * 60 * 1000);
+    ipcHandler = () => {
+      throw new Error("ENOENT");
+    };
+
+    for (let i = 0; i < 100; i++) {
+      _clearGlobalCacheForTesting(); // force re-fetch each call
+      await getAutoApproveThreshold(undefined, "background");
+    }
+
+    const warns = logCalls.filter((c) => c.level === "warn");
+    // At most one WARN — the very first call. All 99 follow-ups suppressed.
+    expect(warns.length).toBe(1);
+
+    const state = _getFailureStateForTesting("global_thresholds");
+    expect(state?.consecutiveFailures).toBe(100);
+  });
+
+  test("a fresh WARN fires once the cadence window elapses", async () => {
+    // 5ms window so the test runs fast.
+    _setFailureWarnIntervalForTesting(5);
+    ipcHandler = () => {
+      throw new Error("ENOENT");
+    };
+
+    await getAutoApproveThreshold(undefined, "background");
+    expect(logCalls.filter((c) => c.level === "warn").length).toBe(1);
+
+    // Wait past the window then fail again.
+    await new Promise((r) => setTimeout(r, 20));
+    _clearGlobalCacheForTesting();
+    await getAutoApproveThreshold(undefined, "background");
+
+    const warns = logCalls.filter((c) => c.level === "warn");
+    expect(warns.length).toBe(2);
+    // Second WARN includes the streak metadata so dashboards can see how
+    // many failures were swallowed in between.
+    expect(warns[1]?.fields).toMatchObject({
+      op: "global_thresholds",
+      consecutiveFailures: 2,
+      event: "ipc_threshold_failure",
+    });
+    expect(warns[1]?.fields.streakDurationMs).toBeDefined();
+  });
+
+  test("recovery emits an INFO with the swallowed-failure count and clears state", async () => {
+    _setFailureWarnIntervalForTesting(60 * 60 * 1000);
+    let working = false;
+    ipcHandler = (method) => {
+      if (working && method === "get_global_thresholds") {
+        return { interactive: "medium", autonomous: "low" };
+      }
+      throw new Error("ENOENT");
+    };
+
+    // Three failures, then it recovers.
+    for (let i = 0; i < 3; i++) {
+      _clearGlobalCacheForTesting();
+      await getAutoApproveThreshold(undefined, "background");
+    }
+    expect(_getFailureStateForTesting("global_thresholds")?.consecutiveFailures).toBe(
+      3,
+    );
+
+    working = true;
+    _clearGlobalCacheForTesting();
+    expect(await getAutoApproveThreshold(undefined, "background")).toBe("low");
+
+    const infos = logCalls.filter((c) => c.level === "info");
+    expect(infos.length).toBe(1);
+    expect(infos[0]?.fields).toMatchObject({
+      op: "global_thresholds",
+      swallowedFailures: 3,
+      event: "ipc_threshold_recovered",
+    });
+    expect(infos[0]?.fields.streakDurationMs).toBeDefined();
+
+    expect(_getFailureStateForTesting("global_thresholds")).toBeUndefined();
+  });
+
+  test("conversation and global ops have independent failure streaks", async () => {
+    _setFailureWarnIntervalForTesting(60 * 60 * 1000);
+    // conversation IPC fails (transport — returns undefined), global IPC works.
+    ipcHandler = (method) => {
+      if (method === "get_conversation_threshold") return undefined;
+      if (method === "get_global_thresholds") {
+        return { interactive: "medium", autonomous: "low" };
+      }
+      return undefined;
+    };
+
+    // First call: conversation transport fails, global succeeds.
+    expect(await getAutoApproveThreshold("conv-1", "conversation")).toBe(
+      "medium",
+    );
+
+    expect(
+      _getFailureStateForTesting("conversation_threshold")?.consecutiveFailures,
+    ).toBe(1);
+    expect(_getFailureStateForTesting("global_thresholds")).toBeUndefined();
+
+    const warns = logCalls.filter((c) => c.level === "warn");
+    expect(warns.length).toBe(1);
+    expect(warns[0]?.fields.op).toBe("conversation_threshold");
+  });
+
+  test("a successful conversation override clears the conversation streak even when the gateway returns null (no override)", async () => {
+    _setFailureWarnIntervalForTesting(60 * 60 * 1000);
+
+    // First two calls: conversation IPC returns undefined (transport failure).
+    let working = false;
+    ipcHandler = (method) => {
+      if (method === "get_conversation_threshold") {
+        return working ? null : undefined;
+      }
+      if (method === "get_global_thresholds") {
+        return { interactive: "low", autonomous: "none" };
+      }
+      return undefined;
+    };
+
+    // Force two transport failures.
+    await getAutoApproveThreshold("conv-2", "conversation");
+    await new Promise((r) => setTimeout(r, 6)); // bypass the 5s convo cache
+    _clearGlobalCacheForTesting();
+    // Convo cache is keyed on conversationId — change the id to bypass.
+    await getAutoApproveThreshold("conv-3", "conversation");
+    expect(
+      _getFailureStateForTesting("conversation_threshold")?.consecutiveFailures,
+    ).toBe(2);
+
+    // Now the IPC starts working — even a null "no override" response is a
+    // successful round-trip and must clear the streak.
+    working = true;
+    _clearGlobalCacheForTesting();
+    await getAutoApproveThreshold("conv-4", "conversation");
+
+    const infos = logCalls.filter((c) => c.level === "info");
+    expect(infos.length).toBe(1);
+    expect(infos[0]?.fields).toMatchObject({
+      op: "conversation_threshold",
+      swallowedFailures: 2,
+      event: "ipc_threshold_recovered",
+    });
+    expect(_getFailureStateForTesting("conversation_threshold")).toBeUndefined();
+  });
+});

package/bun.lock

@@ -18,6 +18,7 @@
         "@vellumai/credential-storage": "file:../packages/credential-storage",
         "@vellumai/egress-proxy": "file:../packages/egress-proxy",
         "@vellumai/gateway-client": "file:../packages/gateway-client",
+        "@vellumai/ipc-server-utils": "file:../packages/ipc-server-utils",
         "@vellumai/service-contracts": "file:../packages/service-contracts",
         "@vellumai/skill-host-contracts": "file:../packages/skill-host-contracts",
         "@vellumai/slack-text": "file:../packages/slack-text",
@@ -421,6 +422,8 @@
 
     "@vellumai/gateway-client": ["@vellumai/gateway-client@file:../packages/gateway-client", { "dependencies": { "@vellumai/service-contracts": "file:../service-contracts" }, "devDependencies": { "@types/bun": "1.3.10", "typescript": "5.9.3" } }],
 
+    "@vellumai/ipc-server-utils": ["@vellumai/ipc-server-utils@file:../packages/ipc-server-utils", { "devDependencies": { "@types/bun": "1.3.10", "typescript": "5.9.3" } }],
+
     "@vellumai/service-contracts": ["@vellumai/service-contracts@file:../packages/service-contracts", { "dependencies": { "zod": "4.3.6" }, "devDependencies": { "@types/bun": "1.2.4", "typescript": "5.7.3" } }],
 
     "@vellumai/skill-host-contracts": ["@vellumai/skill-host-contracts@file:../packages/skill-host-contracts", { "devDependencies": { "@types/bun": "1.3.10", "typescript": "5.9.3" } }],

package/knip.json

@@ -11,6 +11,7 @@
     "@vellumai/credential-storage",
     "@vellumai/egress-proxy",
     "@vellumai/gateway-client",
+    "@vellumai/ipc-server-utils",
     "@vellumai/service-contracts",
     "@vellumai/slack-text",
     "@vellumai/twilio-client",

package/node_modules/@vellumai/ipc-server-utils/bun.lock

@@ -0,0 +1,24 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@vellumai/ipc-server-utils",
+      "devDependencies": {
+        "@types/bun": "1.3.10",
+        "typescript": "5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.10", "", { "dependencies": { "bun-types": "1.3.10" } }, "sha512-0+rlrUrOrTSskibryHbvQkDOWRJwJZqZlxrUs1u4oOoTln8+WIXBPmAuCF35SWB2z4Zl3E84Nl/D0P7803nigQ=="],
+
+    "@types/node": ["@types/node@25.6.0", "", { "dependencies": { "undici-types": "~7.19.0" } }, "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ=="],
+
+    "bun-types": ["bun-types@1.3.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-tcpfCCl6XWo6nCVnpcVrxQ+9AYN1iqMIzgrSKYMB/fjLtV2eyAVEg7AxQJuCq/26R6HpKWykQXuSOq/21RYcbg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.19.2", "", {}, "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg=="],
+  }
+}

package/node_modules/@vellumai/ipc-server-utils/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@vellumai/ipc-server-utils",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.10",
+    "typescript": "5.9.3"
+  }
+}

package/node_modules/@vellumai/ipc-server-utils/src/index.ts

@@ -0,0 +1,6 @@
+export {
+  SocketWatchdog,
+  ensureSocketDir,
+  type SocketWatchdogOptions,
+  type SocketWatchdogLogger,
+} from "./socket-watchdog.js";