@vellumai/assistant 0.12.3 → 0.12.4-dev.202609231620.a15f321

package/src/tools/skills/load.ts

@@ -35,6 +35,7 @@ import type {
   ToolDefinition,
   ToolExecutionResult,
 } from "../types.js";
+import { formatSkillInputSchema } from "./format-input-schema.js";
 
 /** Skill sources eligible for inline command expansion in v1. */
 const INLINE_COMMAND_ELIGIBLE_SOURCES = new Set([
@@ -123,32 +124,7 @@ function formatToolSchemas(
       tool.description.replaceAll("{workspaceDir}", getWorkspaceDirDisplay()),
     );
 
-    const schema = tool.input_schema;
-    const properties = schema.properties as
-      | Record<string, Record<string, unknown>>
-      | undefined;
-    if (properties && Object.keys(properties).length > 0) {
-      const requiredSet = new Set<string>(
-        Array.isArray(schema.required) ? (schema.required as string[]) : [],
-      );
-
-      lines.push("Parameters:");
-      for (const [paramName, paramDef] of Object.entries(properties)) {
-        const paramType =
-          typeof paramDef.type === "string" ? paramDef.type : "any";
-        const requiredLabel = requiredSet.has(paramName)
-          ? "required"
-          : "optional";
-        const descPart =
-          typeof paramDef.description === "string"
-            ? `: ${paramDef.description.replaceAll("{workspaceDir}", getWorkspaceDirDisplay())}`
-            : "";
-        lines.push(
-          `- ${paramName} (${paramType}, ${requiredLabel})${descPart}`,
-        );
-      }
-    }
-
+    lines.push(formatSkillInputSchema(tool.input_schema));
     lines.push("");
   }
 
@@ -181,6 +157,7 @@ export const skillLoadTool = {
   async execute(
     input: Record<string, unknown>,
     context: ToolContext,
+    options?: { readOnly?: boolean },
   ): Promise<ToolExecutionResult> {
     const selector = input.skill;
     if (typeof selector !== "string" || selector.trim().length === 0) {
@@ -195,13 +172,17 @@ export const skillLoadTool = {
     // command execution. Instructions are still returned so the assistant can
     // load the system-storage-cleanup skill (and any already-installed skill).
     const cleanupMode = context.diskPressureCleanupModeActive === true;
+    const readOnly = cleanupMode || options?.readOnly === true;
+    const inlineCommandStub = cleanupMode
+      ? INLINE_COMMAND_CLEANUP_STUB
+      : "[inline command not executed]";
 
     let loaded = loadSkillBySelector(selector);
 
     // Auto-install from catalog if the skill isn't found locally
     if (
       !loaded.skill &&
-      !cleanupMode &&
+      !readOnly &&
       (loaded.errorCode === "not_found" || loaded.errorCode === "empty_catalog")
     ) {
       try {
@@ -297,9 +278,8 @@ export const skillLoadTool = {
           break;
         }
 
-        // Under the disk-pressure lock, never auto-install missing includes
-        // (that writes to the workspace). Leave them advisory ("not loaded").
-        if (cleanupMode) {
+        // Read-only loads leave missing includes advisory ("not loaded").
+        if (readOnly) {
           break;
         }
 
@@ -373,17 +353,11 @@ export const skillLoadTool = {
     const hasInlineCommands =
       skill.inlineCommandExpansions && skill.inlineCommandExpansions.length > 0;
 
-    if (hasInlineCommands && cleanupMode) {
-      // Under the disk-pressure lock, loading a skill must not execute shell.
-      // Strip inline command tokens instead of rendering them; the rest of the
-      // instructions are still returned.
-      body = body.replace(
-        INLINE_COMMAND_TOKEN_PATTERN,
-        INLINE_COMMAND_CLEANUP_STUB,
-      );
+    if (hasInlineCommands && readOnly) {
+      body = body.replace(INLINE_COMMAND_TOKEN_PATTERN, inlineCommandStub);
       log.info(
         { skillId: skill.id },
-        "Skipped inline command expansion during disk pressure cleanup mode",
+        "Skipped inline command expansion during read-only skill load",
       );
     } else if (hasInlineCommands) {
       if (skill.source === "extra" || skill.source === "plugin") {
@@ -475,12 +449,10 @@ export const skillLoadTool = {
             childLoaded.skill.inlineCommandExpansions &&
             childLoaded.skill.inlineCommandExpansions.length > 0;
 
-          if (childHasInlineCommands && cleanupMode) {
-            // No shell execution under the disk-pressure lock — strip the
-            // child's inline command tokens rather than rendering them.
+          if (childHasInlineCommands && readOnly) {
             childBody = childBody.replace(
               INLINE_COMMAND_TOKEN_PATTERN,
-              INLINE_COMMAND_CLEANUP_STUB,
+              inlineCommandStub,
             );
           } else if (childHasInlineCommands) {
             if (

package/src/tools/skills/scaffold-managed.ts

@@ -1,14 +1,16 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 
+import { v4 as uuid } from "uuid";
+
 import type { SkillSource } from "../../config/skills.js";
 import { loadSkillCatalog } from "../../config/skills.js";
 import { refreshSkillCapabilityMemories } from "../../daemon/skill-memory-refresh.js";
-import { emitNotificationSignal } from "../../notifications/emit-signal.js";
 import { sanitizeMultilineMessagePreview } from "../../notifications/notification-utils.js";
 import { getConversation } from "../../persistence/conversation-crud.js";
 import { upsertSkillCardInsertJob } from "../../persistence/jobs-store.js";
 import { MEMORY_RETROSPECTIVE_ORIGIN } from "../../plugins/defaults/memory/memory-retrospective-constants.js";
+import { recordSkillUpdate } from "../../plugins/defaults/memory/skill-update-receipt-job.js";
 import { readInstallMeta } from "../../skills/install-meta.js";
 import {
   createManagedSkill,
@@ -90,78 +92,90 @@ function normalizeOptionalStringArray(
   return { value: normalized };
 }
 
+/** Watchdog check_name counted when a receipt entry could not be recorded. */
+const SKILL_UPDATE_RECEIPT_RECORD_FAILED_CHECK_NAME =
+  "skill_update_receipt_record_failed";
+
 /**
- * Tell the user that a background pass changed a skill they already have.
+ * Record that a background pass changed a skill the user already has.
  *
  * A newly authored skill announces itself in the conversation through the
- * `skill_card` surface; an update announces itself here instead. The pass
- * runs in a background fork and rewrites the body of a skill the user may be
- * relying on, and `createManagedSkill` writes through an atomic rename
- * keeping no prior version, so the notification pipeline is what puts the
- * change in the background feed alongside the other unattended work (sweeps,
- * scheduled jobs, heartbeat), where a user already looks to see what the
- * assistant did on its own.
+ * `skill_card` surface; an update is announced through a skill-update
+ * receipt instead. The pass runs in a background fork and rewrites the body
+ * of a skill the user may be relying on, and `createManagedSkill` writes
+ * through an atomic rename keeping no prior version, so the receipt is what
+ * puts the change in the background feed alongside the other unattended
+ * work (sweeps, scheduled jobs, heartbeat), where a user already looks to
+ * see what the assistant did on its own. One pass can rewrite several skills
+ * within minutes, so the rewrites accumulate on one pending receipt job
+ * (`plugins/defaults/memory/skill-update-receipt-job.ts`), which announces
+ * the whole burst once it has settled rather than one notification per
+ * rewrite.
  *
  * `changeSummary` is the pass's own account of what it changed and is the
- * notice's body: the feed item is the only place the change surfaces, and a
- * reader triaging it there has no diff to look at, so a notice that only
+ * entry's body: the receipt is the only place the change surfaces, and a
+ * reader triaging it there has no diff to look at, so an entry that only
  * names the skill sends them into the skill to find out what happened. The
  * executor refuses the overwrite without one, so this never runs without it.
  *
- * `sourceContextId` is a conversation id so the feed item's "Go to Convo"
- * target resolves (see `home-feed-side-effect.ts`, which looks it up via
- * `getConversation`): the source conversation when lineage resolved, else the
- * run's own conversation. Deduped per skill per day, so a pass that refines
- * the same skill repeatedly cannot flood the feed. Best-effort and
- * non-blocking: the skill is already written, and a notification failure must
- * never turn that into a tool error.
+ * `sourceConversationId` is the conversation the receipt's link resolves to
+ * for this entry (see `home-updates-list.tsx`): the source conversation when
+ * lineage resolved, else none. The run's own conversation is never used in
+ * its place: it is an ephemeral fork the next successful retrospective
+ * garbage-collects, and the receipt job leaves out any entry whose source
+ * is gone by the time it announces, so naming the fork would drop the
+ * entry rather than link it. `entryId` is the producing tool call's id, so a
+ * re-executed call records nothing new. A context with no tool call id (a
+ * direct caller) has no re-execution to guard against, so it gets a fresh
+ * id: a stable key on the run and skill would drop a second rewrite of the
+ * same skill in the same run.
+ *
+ * Best-effort and non-blocking: the skill is already written, and a receipt
+ * that cannot be recorded is a receipt the user will not get, not a reason
+ * to fail or retry a write that already landed. The failure is logged with
+ * the ids and counted, and the tool-invocation history keeps the summary as
+ * audit evidence.
  */
-function notifyBackgroundSkillUpdate(args: {
+function recordBackgroundSkillUpdate(args: {
   skillId: string;
   name: string;
-  conversationId: string;
   changeSummary: string;
+  runConversationId: string;
+  sourceConversationId: string | undefined;
+  toolUseId: string | undefined;
 }): void {
-  const day = new Date().toISOString().slice(0, 10);
-  void emitNotificationSignal({
-    // This emit is a tool executor's, not the scheduler's. The channel is
-    // provenance the pipeline reads: `home-feed-side-effect` derives
-    // `fromAssistant` from it, so labelling this "scheduler" would drop the
-    // item from the feed's assistant-initiated filter despite being exactly
-    // that.
-    sourceChannel: "assistant_tool",
-    sourceContextId: args.conversationId,
-    sourceEventName: "activity.complete",
-    dedupeKey: `skill-updated:${args.skillId}:${day}`,
-    contextPayload: {
-      // `summary` feeds the copy composer and `title` is the headline both
-      // it and the home feed keep; `title`/`body` are also the feed's
-      // fallback when no channel copy was rendered. Without them a fully
-      // suppressed delivery (the intended shape for this signal: low urgency,
-      // background, no interruption) leaves the feed writer with no summary
-      // and it skips the item entirely, so the quiet case would surface
-      // nothing at all.
-      summary: args.changeSummary,
-      // Named, not just "Skill updated": the feed sits several rows deep and
-      // a generic title is unscannable next to entries that name their
-      // subject (`Background job failed: memory.v2.sweep`). The word "Skill"
-      // stays because a bare skill name does not always read as one.
-      title: `Skill updated: ${args.name}`,
-      body: args.changeSummary,
+  const entryId = `${args.runConversationId}:${args.toolUseId ?? uuid()}`;
+  try {
+    recordSkillUpdate({
+      entryId,
       skillId: args.skillId,
-    },
-    attentionHints: {
-      requiresAction: false,
-      urgency: "low",
-      isAsyncBackground: true,
-      visibleInSourceNow: false,
-    },
-  }).catch((err: unknown) => {
+      name: args.name,
+      changeSummary: args.changeSummary,
+      runConversationId: args.runConversationId,
+      ...(args.sourceConversationId
+        ? { sourceConversationId: args.sourceConversationId }
+        : {}),
+    });
+  } catch (err) {
     log.warn(
-      { err, skillId: args.skillId },
-      "skill update notification failed; the skill write stands",
+      {
+        err,
+        skillId: args.skillId,
+        runConversationId: args.runConversationId,
+        entryId,
+      },
+      "skill update receipt recording failed; the skill write stands and no receipt will name this update",
     );
-  });
+    try {
+      recordWatchdogEvent({
+        checkName: SKILL_UPDATE_RECEIPT_RECORD_FAILED_CHECK_NAME,
+        value: 1,
+      });
+    } catch {
+      // recordWatchdogEvent already no-ops on opt-out and a missing
+      // telemetry DB; anything past that is not worth surfacing here.
+    }
+  }
 }
 
 /**
@@ -333,10 +347,11 @@ export async function executeScaffoldManagedSkill(
     category = input.category.trim().toLowerCase();
   }
 
-  // The update notice's body. Model-authored text bound for a notification
+  // The receipt entry's body. Model-authored text bound for a notification
   // surface, so it gets the same control-character strip and preview clamp as
   // any other producer-supplied body; blank collapses to absent so the
-  // requirement below treats it as missing rather than posting an empty notice.
+  // requirement below treats it as missing rather than recording an empty
+  // entry.
   let changeSummary: string | undefined;
   if (input.change_summary !== undefined) {
     if (typeof input.change_summary !== "string") {
@@ -404,9 +419,9 @@ export async function executeScaffoldManagedSkill(
     }
   }
 
-  // A background overwrite announces itself through the notice built in
-  // notifyBackgroundSkillUpdate, whose body is this summary, so the write is
-  // refused without one. The error returns to the pass in the same turn and
+  // A background overwrite announces itself through the receipt entry
+  // recorded in recordBackgroundSkillUpdate, whose body is this summary, so
+  // the write is refused without one. The error returns to the pass in the same turn and
   // it retries with the field, the way a missing activation_hints does.
   // Checked after the ownership backstop so a pass that may not touch the
   // skill hears that first, and only for a call that asked to overwrite: a
@@ -500,23 +515,23 @@ export async function executeScaffoldManagedSkill(
   }
 
   // A background pass changed a skill that already existed. Creates announce
-  // themselves through the skill card below; updates announce themselves in
-  // the background activity feed. Covers an explicit `overwrite: true`
-  // refinement as well as any other background write onto a pre-existing
-  // skill.
-  const notifyConversationId =
-    sourceConversationId ?? retrospectiveConversationId;
+  // themselves through the skill card below; updates land on the skill-update
+  // receipt that announces the whole burst. Covers an explicit
+  // `overwrite: true` refinement as well as any other background write onto
+  // a pre-existing skill.
   if (
     fromRetrospective &&
     managedSkillExistedBefore &&
-    notifyConversationId &&
+    retrospectiveConversationId &&
     changeSummary
   ) {
-    notifyBackgroundSkillUpdate({
+    recordBackgroundSkillUpdate({
       skillId: id,
       name: normalizedName,
-      conversationId: notifyConversationId,
       changeSummary,
+      runConversationId: retrospectiveConversationId,
+      sourceConversationId,
+      toolUseId: context.toolUseId,
     });
   }
 

package/src/tools/skills/skill-tool-factory.ts

@@ -15,6 +15,7 @@ import { bundledToolInputMisuseMessage } from "../shared/input-misuse.js";
 import { bundledToolInputRepairs } from "../shared/input-repairs.js";
 import type { ExecutionTarget } from "../tool-types.js";
 import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
+import { formatSkillInputSchema } from "./format-input-schema.js";
 import { runSkillToolScript } from "./skill-script-runner.js";
 
 const riskMap: Record<SkillToolEntry["risk"], RiskLevel> = {
@@ -94,7 +95,7 @@ export function createSkillTool(
         return {
           content:
             misuse ??
-            `Invalid input for tool "${entry.name}": ${validation.errors.join("; ")}. Fix the arguments and retry.`,
+            `Invalid input for tool "${entry.name}": ${validation.errors.join("; ")}. If skill_load is available, load the owning skill for its current instructions. Retry with arguments matching this schema.\n\n${formatSkillInputSchema(entry.input_schema)}`,
           isError: true,
         };
       }

package/src/tools/workflows/manage-workflows.ts

@@ -15,7 +15,7 @@
 
 import { z } from "zod";
 
-import { getUserSelectableProfilesForProvider } from "../../config/default-profile-catalog.js";
+import { getConversationProfilesForProvider } from "../../config/default-profile-catalog.js";
 import { loadConfig } from "../../config/loader.js";
 import { callerOwnsWorkflowRun } from "../../workflows/capabilities.js";
 import type { WorkflowRun } from "../../workflows/journal-store.js";
@@ -199,7 +199,9 @@ export async function executeManageWorkflows(
       // workspace-wide active profile. Read-only — leaves use this to pick a
       // valid `profile` for `run_workflow` (an unknown profile throws).
       const { llm } = loadConfig();
-      const profiles = getUserSelectableProfilesForProvider(
+      // A workflow leaf runs chat turns, so this is the conversation view,
+      // which leaves out the managed Jev profile.
+      const profiles = getConversationProfilesForProvider(
         llm?.profiles,
         llm?.defaultProvider ?? null,
       );

package/src/util/worker-pipe.test.ts

@@ -0,0 +1,146 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { writeWorkerLine } from "./worker-pipe.js";
+
+/** Comfortably larger than any OS pipe buffer, so the write cannot complete. */
+const OVERSIZED_LINE = "x".repeat(4 * 1024 * 1024);
+
+const spawned: { kill(signal?: NodeJS.Signals): void }[] = [];
+
+afterEach(() => {
+  for (const proc of spawned.splice(0)) {
+    try {
+      proc.kill("SIGKILL");
+    } catch {
+      /* already gone */
+    }
+  }
+});
+
+/** A live child that never reads stdin, the way a worker busy in ONNX does not. */
+function spawnBusyWorker() {
+  const proc = Bun.spawn({
+    cmd: [process.execPath, "-e", "setTimeout(() => {}, 60_000)"],
+    windowsHide: true,
+    stdin: "pipe",
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  spawned.push(proc);
+  return proc;
+}
+
+describe("writeWorkerLine", () => {
+  /**
+   * The contract this module rests on, against the real Bun API: a payload
+   * that outruns the pipe buffer comes back as a `Promise`, and killing the
+   * worker settles it. Which way it settles is Bun's to choose. It rejects
+   * with EPIPE on nearly every kill and, rarely on Linux, resolves with a
+   * short count instead, so this asserts only that nothing escapes either
+   * way. Demanding the rejection is what made this case flaky on CI.
+   */
+  test("observes a real pending write however Bun settles it", async () => {
+    const proc = spawnBusyWorker();
+    const failures: unknown[] = [];
+    const settling: Promise<number>[] = [];
+    const record = (result: number | Promise<number>) => {
+      if (result instanceof Promise) {
+        settling.push(result);
+      }
+      return result;
+    };
+
+    writeWorkerLine(
+      {
+        write: (chunk) => record(proc.stdin.write(chunk)),
+        flush: () => record(proc.stdin.flush()),
+      },
+      OVERSIZED_LINE,
+      (err) => failures.push(err),
+    );
+    proc.kill("SIGKILL");
+    const outcomes = await Promise.race([
+      Promise.allSettled(settling),
+      Bun.sleep(10_000).then(() => null),
+    ]);
+
+    expect(settling.length).toBeGreaterThan(0);
+    expect(outcomes).not.toBeNull();
+    expect(failures).toHaveLength(
+      outcomes!.some((o) => o.status === "rejected") ? 1 : 0,
+    );
+  });
+
+  /**
+   * The production failure: the payload outruns the pipe buffer, Bun hands
+   * `write` and `flush` one pending promise, and the worker dies before
+   * draining it. Bun rejects that promise from its own event loop, after this
+   * call has returned. Unobserved, the rejection is an `unhandledRejection`,
+   * which `bun test` reports as a failure of this test.
+   */
+  test("reports a write still pending when the worker dies", async () => {
+    const failure = Promise.withResolvers<unknown>();
+    const epipe = Object.assign(new Error("EPIPE: broken pipe, write"), {
+      code: "EPIPE",
+    });
+    const pending = Promise.withResolvers<number>();
+    const stdin = {
+      write: () => pending.promise,
+      flush: () => pending.promise,
+    };
+
+    writeWorkerLine(stdin, "line", failure.resolve);
+    pending.reject(epipe);
+
+    expect(await failure.promise).toBe(epipe);
+  });
+
+  test("reports a synchronous throw", () => {
+    const failures: unknown[] = [];
+    const epipe = Object.assign(new Error("EPIPE: broken pipe, write"), {
+      code: "EPIPE",
+    });
+    const stdin = {
+      write() {
+        throw epipe;
+      },
+      flush: () => 0,
+    };
+
+    writeWorkerLine(stdin, "line", (err) => failures.push(err));
+
+    expect(failures).toEqual([epipe]);
+  });
+
+  /** `write` and `flush` both report the same broken pipe. */
+  test("reports one failure when write and flush both reject", async () => {
+    const failures: unknown[] = [];
+    const epipe = new Error("EPIPE: broken pipe, send");
+    const stdin = {
+      write: () => Promise.reject(epipe),
+      flush: () => Promise.reject(epipe),
+    };
+
+    writeWorkerLine(stdin, "line", (err) => failures.push(err));
+    await Bun.sleep(0);
+
+    expect(failures).toEqual([epipe]);
+  });
+
+  test("stays silent when the line is delivered", async () => {
+    const failures: unknown[] = [];
+    const proc = Bun.spawn({
+      cmd: [process.execPath, "-e", "process.stdin.on('data', () => {})"],
+      windowsHide: true,
+      stdin: "pipe",
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    spawned.push(proc);
+
+    writeWorkerLine(proc.stdin, "hello", (err) => failures.push(err));
+    await Bun.sleep(50);
+
+    expect(failures).toEqual([]);
+  });
+});

package/src/util/worker-pipe.ts

@@ -0,0 +1,49 @@
+import type { FileSink } from "bun";
+
+/**
+ * Write one line to a worker subprocess's stdin, reporting a broken pipe to
+ * `onFailure` however Bun surfaces it.
+ *
+ * `FileSink.write` and `FileSink.flush` return `number | Promise<number>`.
+ * While the pipe has room they complete synchronously. Once a payload outruns
+ * the pipe buffer, which is what happens when the worker is busy and not
+ * draining stdin, they return a pending promise instead, and that promise
+ * rejects with EPIPE once the worker dies, from Bun's event loop, after this
+ * call has returned. A `try/catch` sees only the synchronous half: the
+ * rejection escapes it, reaches the process's `unhandledRejection` handler,
+ * and in the daemon that handler shuts the whole process down.
+ *
+ * On Linux, Bun occasionally treats a zero-byte write to the dead worker's
+ * pipe as end-of-file and resolves that promise with the bytes written so
+ * far instead. `onFailure` then never runs, and the caller learns of the
+ * death only when the worker's stdout ends.
+ *
+ * `onFailure` runs at most once per call, even though `write` and `flush` can
+ * each report the same broken pipe.
+ */
+export function writeWorkerLine(
+  stdin: Pick<FileSink, "write" | "flush">,
+  line: string,
+  onFailure: (err: unknown) => void,
+): void {
+  let failed = false;
+  const fail = (err: unknown): void => {
+    if (failed) {
+      return;
+    }
+    failed = true;
+    onFailure(err);
+  };
+  const observe = (result: number | Promise<number>): void => {
+    if (result instanceof Promise) {
+      result.catch(fail);
+    }
+  };
+
+  try {
+    observe(stdin.write(line + "\n"));
+    observe(stdin.flush());
+  } catch (err) {
+    fail(err);
+  }
+}