@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/schedule/worker.ts

@@ -0,0 +1,131 @@
+/**
+ * Standalone entry point for the schedule worker as its own OS process.
+ *
+ * Spawned by `assistant schedules worker start` (and at daemon startup when
+ * `schedules.worker.enabled` is set). Loads config, writes a PID file, and
+ * claims + executes due schedules (all modes) on a fixed tick until
+ * SIGTERM/SIGINT. While the flag is set, the daemon's in-process scheduler
+ * leaves schedules to this process.
+ *
+ * Running as a separate process — off the assistant's main event loop — is
+ * the point: expensive scheduled jobs execute here without competing with
+ * user-facing traffic, and keep running during a main-thread freeze in the
+ * daemon.
+ */
+
+import { existsSync, unlinkSync, writeFileSync } from "node:fs";
+
+import { getConfig } from "../config/loader.js";
+import { initializeTools } from "../tools/registry.js";
+import { getLogger } from "../util/logger.js";
+import { getScheduleWorkerPidPath } from "../util/platform.js";
+import { runDueSchedulesOnce } from "./scheduler.js";
+
+const log = getLogger("schedule-worker-process");
+
+/** Same cadence as the daemon scheduler's tick. */
+const TICK_INTERVAL_MS = 15_000;
+
+function cleanupPidFile(): void {
+  const pidPath = getScheduleWorkerPidPath();
+  try {
+    if (existsSync(pidPath)) {
+      unlinkSync(pidPath);
+    }
+  } catch {
+    // best-effort
+  }
+}
+
+async function main(): Promise<void> {
+  // Load config up front so a broken config fails the spawn (before the PID
+  // file is written) instead of surfacing on the first tick.
+  getConfig();
+  const pidPath = getScheduleWorkerPidPath();
+
+  // Write PID file so `status` and `stop` can find us.
+  writeFileSync(pidPath, String(process.pid), { flag: "w" });
+  log.info({ pid: process.pid, pidPath }, "Schedule worker process started");
+
+  // Populate the tool registry (core built-ins + workspace tools). The daemon
+  // does this at startup; this standalone process has to do it itself so
+  // workflow schedules pass the core-tools readiness gate and agent-executed
+  // schedules run with their tools. Best-effort — a tool-registry failure
+  // must not take the worker down with it.
+  try {
+    await initializeTools();
+  } catch (err) {
+    log.warn(
+      { err },
+      "Failed to initialize tools in schedule worker; continuing degraded",
+    );
+  }
+
+  let stopped = false;
+  let tickRunning = false;
+  const tick = async () => {
+    if (stopped || tickRunning) {
+      return;
+    }
+    tickRunning = true;
+    try {
+      const result = await runDueSchedulesOnce();
+      const processed = result.completed + result.failed + result.skipped;
+      if (processed > 0) {
+        log.info({ processed }, "Schedule worker tick complete");
+      }
+    } catch (err) {
+      log.error({ err }, "Schedule worker tick failed");
+    } finally {
+      tickRunning = false;
+    }
+  };
+
+  // Deliberately ref'd (unlike the daemon scheduler's timer): this interval
+  // is what keeps the standalone process alive between ticks.
+  const timer = setInterval(() => {
+    void tick();
+  }, TICK_INTERVAL_MS);
+  void tick();
+
+  const shutdown = (signal: string) => {
+    log.info({ signal }, "Schedule worker process shutting down");
+    stopped = true;
+    clearInterval(timer);
+    cleanupPidFile();
+    process.exit(0);
+  };
+
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+
+  // Catch stray exceptions that escape the tick loop so they produce a clean
+  // pino-formatted log entry (and PID-file cleanup) instead of a raw stack
+  // trace on stderr. The stderr fd is already piped to the log file by the
+  // spawner, so even without these handlers the trace would be captured —
+  // but this gives us structured logging and graceful shutdown.
+  process.on("uncaughtException", (err) => {
+    log.error({ err }, "Uncaught exception in schedule worker process");
+    cleanupPidFile();
+    process.exit(1);
+  });
+
+  process.on("unhandledRejection", (reason) => {
+    log.error({ reason }, "Unhandled rejection in schedule worker process");
+    cleanupPidFile();
+    process.exit(1);
+  });
+
+  // Clean up if the process exits unexpectedly through any other path.
+  process.on("exit", () => {
+    stopped = true;
+    clearInterval(timer);
+    cleanupPidFile();
+  });
+}
+
+void main().catch((err) => {
+  log.error({ err }, "Schedule worker process failed to start");
+  cleanupPidFile();
+  process.exit(1);
+});

package/src/skills/__tests__/categories-cache.test.ts

@@ -0,0 +1,38 @@
+import { join } from "node:path";
+import { describe, expect, mock, test } from "bun:test";
+
+// Control what getRepoSkillsDir() returns per test. Mocked before the module
+// under test is imported so getLocalCategorySlugs() sees the override.
+let repoSkillsDirOverride: string | undefined;
+
+mock.module("../catalog-install.js", () => ({
+  getRepoSkillsDir: () => repoSkillsDirOverride,
+}));
+
+const { getLocalCategorySlugs } = await import("../categories-cache.js");
+
+// Repo-root `skills/` relative to this test file
+// (assistant/src/skills/__tests__ -> repo root -> skills).
+const REAL_SKILLS_DIR = join(import.meta.dir, "..", "..", "..", "..", "skills");
+
+describe("getLocalCategorySlugs", () => {
+  test("resolves slugs via getRepoSkillsDir when it is available", () => {
+    repoSkillsDirOverride = REAL_SKILLS_DIR;
+    const slugs = getLocalCategorySlugs();
+    expect(slugs.has("development")).toBe(true);
+    expect(slugs.has("system")).toBe(true);
+  });
+
+  test("falls back to the module-relative catalog when getRepoSkillsDir is undefined (Docker source-run)", () => {
+    // Regression: in Docker mode the launcher runs `bun run src/index.ts`
+    // without VELLUM_DEV, so getRepoSkillsDir() returns undefined. The reader
+    // previously returned an empty set, which made normalizeMarketplaceCategory
+    // treat every marketplace category as invalid and bucket all plugins under
+    // System. The module-relative fallback must still resolve the bundled YAML.
+    repoSkillsDirOverride = undefined;
+    const slugs = getLocalCategorySlugs();
+    expect(slugs.size).toBeGreaterThan(0);
+    expect(slugs.has("development")).toBe(true);
+    expect(slugs.has("system")).toBe(true);
+  });
+});

package/src/skills/categories-cache.ts

@@ -37,7 +37,9 @@ async function fetchCategories(): Promise<SkillCategoryDef[]> {
     categories: SkillCategoryDef[];
   };
   if (!Array.isArray(data.categories)) {
-    throw new Error("Platform categories response has invalid categories array");
+    throw new Error(
+      "Platform categories response has invalid categories array",
+    );
   }
   return data.categories.filter(
     (c): c is SkillCategoryDef =>
@@ -75,10 +77,7 @@ export async function getCategories(): Promise<SkillCategoryDef[]> {
     const remote = await fetchCategories();
     if (local.length > 0) {
       const localSlugs = new Set(local.map((c) => c.slug));
-      categories = [
-        ...local,
-        ...remote.filter((c) => !localSlugs.has(c.slug)),
-      ];
+      categories = [...local, ...remote.filter((c) => !localSlugs.has(c.slug))];
     } else {
       categories = remote;
     }
@@ -112,6 +111,42 @@ export function getCachedCategoriesSync(): SkillCategoryDef[] {
   return cachedCategories ?? [];
 }
 
+/**
+ * Valid Skills category slugs, read synchronously from the bundled
+ * `skill-categories-catalog.yaml`. Local + sync so callers that must stay off
+ * the remote path (e.g. the plugins list) get the shared taxonomy without
+ * remote-fetch latency. Resolves the catalog across environments and degrades
+ * to an empty set when it is unreachable — callers treat an empty set as
+ * "everything is unknown" rather than failing.
+ */
+export function getLocalCategorySlugs(): Set<string> {
+  // Primary: getRepoSkillsDir() resolves the catalog for compiled binaries and
+  // VELLUM_DEV dev runs.
+  const repoSkillsDir = getRepoSkillsDir();
+  if (repoSkillsDir) {
+    const slugs = readLocalCategories(repoSkillsDir).map((c) => c.slug);
+    if (slugs.length > 0) return new Set(slugs);
+  }
+  // Fallback for source runs where getRepoSkillsDir() returns undefined (e.g.
+  // the Docker image runs `bun run src/index.ts` without VELLUM_DEV and is not
+  // on the /$bunfs/ path): the catalog is copied to the repo-root `skills/`
+  // dir, resolvable relative to this module (assistant/src/skills -> skills).
+  const moduleRelativeSkillsDir = join(
+    import.meta.dir,
+    "..",
+    "..",
+    "..",
+    "skills",
+  );
+  const relativeSlugs = readLocalCategories(moduleRelativeSkillsDir).map(
+    (c) => c.slug,
+  );
+  if (relativeSlugs.length > 0) return new Set(relativeSlugs);
+  // Last resort: slugs from categories already fetched via the async/remote
+  // path, so normalization still works once that cache is warm.
+  return new Set(getCachedCategoriesSync().map((c) => c.slug));
+}
+
 export function invalidateCategoriesCache(): void {
   cachedCategories = null;
   cacheTimestamp = 0;

package/src/skills/managed-store.ts

@@ -81,10 +81,24 @@ export function validateCompanionPath(
       error: `companion file path must resolve under the skill directory: "${filePath}"`,
     };
   }
-  // A companion write must never clobber a top-level store-owned file: SKILL.md
-  // is the discovery entry point (generated from name/description/body), and the
-  // metadata files carry provenance the store owns.
-  if (RESERVED_COMPANION_NAMES.has(rel.replaceAll(sep, "/"))) {
+  // A companion write must never target a top-level store-owned file: SKILL.md
+  // is the discovery entry point (generated from name/description/body), the
+  // metadata files carry provenance the store owns, and TOOLS.json is reserved
+  // because it is the manifest that registers executable skill tools. Allowing a
+  // scaffold companion write to plant a TOOLS.json would let an author (the
+  // memory retrospective runs unattended over prompt-injectable content) turn an
+  // instruction-only managed skill into one that registers — and dynamically
+  // imports — attacker-controlled executors, a code-injection surface. Managed
+  // skills authored via scaffold carry instructions and reference files only;
+  // executable tools are a first-party/bundled concept.
+  //
+  // The comparison is case-insensitive. The install target includes
+  // case-insensitive filesystems (macOS APFS/HFS+ default), where a companion
+  // written as `tools.json` / `Tools.json` resolves to the very file the
+  // manifest scanner later reads as `TOOLS.json` (and likewise for `skill.md`).
+  // An exact-case check would let a varied-case name slip a manifest past this
+  // guard, so lowercase the candidate before testing membership.
+  if (RESERVED_COMPANION_NAMES.has(rel.replaceAll(sep, "/").toLowerCase())) {
     return {
       error: `companion file path must not overwrite the store-owned file: "${filePath}"`,
     };
@@ -92,11 +106,16 @@ export function validateCompanionPath(
   return { resolvedPath };
 }
 
-/** Top-level files owned by the store; companion writes may never target them. */
+/**
+ * Top-level files owned by the store; companion writes may never target them.
+ * Entries are lowercase — the membership check lowercases the candidate path so
+ * case variants (e.g. `tools.json`) are rejected on case-insensitive filesystems.
+ */
 const RESERVED_COMPANION_NAMES = new Set([
-  "SKILL.md",
+  "skill.md",
   "install-meta.json",
   "version.json",
+  "tools.json",
 ]);
 
 // ─── SKILL.md generation ─────────────────────────────────────────────────────
@@ -107,6 +126,8 @@ interface BuildSkillMarkdownInput {
   bodyMarkdown: string;
   emoji?: string;
   includes?: string[];
+  activationHints?: string[];
+  avoidWhen?: string[];
   category?: string;
 }
 
@@ -132,6 +153,16 @@ export function buildSkillMarkdown(input: BuildSkillMarkdownInput): string {
   if (input.includes && input.includes.length > 0) {
     vellum.includes = input.includes;
   }
+  // Kebab-case keys match what parseFrontmatter reads back
+  // (config/skills.ts: vellum["activation-hints"] / vellum["avoid-when"]).
+  // These flow through stringifyYaml below, which escapes/quotes values, so no
+  // manual sanitization is needed here.
+  if (input.activationHints && input.activationHints.length > 0) {
+    vellum["activation-hints"] = input.activationHints;
+  }
+  if (input.avoidWhen && input.avoidWhen.length > 0) {
+    vellum["avoid-when"] = input.avoidWhen;
+  }
   // The web Skills UI groups skills into a category sidebar by this value;
   // skip it when blank so an empty bucket assignment never lands in frontmatter.
   if (input.category?.trim()) {
@@ -180,6 +211,8 @@ interface CreateManagedSkillParams {
   emoji?: string;
   overwrite?: boolean;
   includes?: string[];
+  activationHints?: string[];
+  avoidWhen?: string[];
   category?: string;
   version?: string;
   contactId?: string;
@@ -262,6 +295,8 @@ export function createManagedSkill(
     bodyMarkdown: params.bodyMarkdown,
     emoji: params.emoji,
     includes: params.includes,
+    activationHints: params.activationHints,
+    avoidWhen: params.avoidWhen,
     category: params.category,
   });
 

package/src/skills/validate-input.ts

@@ -102,6 +102,53 @@ export function coerceStringBooleans(
   return coerced ?? input;
 }
 
+/**
+ * Coerce finite JSON numbers to strings for properties the schema declares as
+ * `type: "string"`.
+ *
+ * Some providers' models emit numeric-looking string values as unquoted JSON
+ * numbers (e.g. a phone number `15550100` instead of `"+15550100"`).
+ * Plain `JSON.parse` yields a JS `Number`, which then fails the validator's
+ * `typeof === "string"` check with a confusing "must be a string" error that
+ * sends the model down a wrong retry path. The value's intent is unambiguous —
+ * a string field received a number — so coerce it the same way we coerce
+ * string-encoded booleans. The E.164 / format / enum checks downstream still
+ * run on the coerced string, so a number missing a `+` prefix still gets a
+ * self-correcting format error rather than a type error.
+ *
+ * Only finite numbers are coerced; `NaN`/`Infinity` (which can't come from
+ * JSON.parse anyway) and non-number types are left untouched. Integers outside
+ * the safe range are also left untouched: `JSON.parse` has already rounded them
+ * (e.g. `12345678901234567890` → `12345678901234567000`), so `String()` would
+ * emit a corrupted identifier. Leaving them un-coerced makes the validator
+ * return a type error, prompting the model to retry with a quoted string that
+ * preserves every digit. Pure: returns a new object when a coercion applies,
+ * otherwise returns `input` unchanged. Never mutates `input` or `schema`.
+ */
+export function coerceStringNumbers(
+  input: Record<string, unknown>,
+  schema: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  if (!schema) return input;
+  const properties = schema.properties;
+  if (!isPlainObject(properties)) return input;
+
+  let coerced: Record<string, unknown> | undefined;
+  for (const [key, rawSubSchema] of Object.entries(properties)) {
+    if (!isPlainObject(rawSubSchema)) continue;
+    if (rawSubSchema.type !== "string") continue;
+    const value = input[key];
+    if (typeof value !== "number" || !Number.isFinite(value)) continue;
+    // An integer beyond the safe range was already rounded by JSON.parse;
+    // coercing it would lock in a corrupted identifier. Skip it so validation
+    // fails and the model retries with a lossless quoted string.
+    if (Number.isInteger(value) && !Number.isSafeInteger(value)) continue;
+    coerced ??= { ...input };
+    coerced[key] = String(value);
+  }
+  return coerced ?? input;
+}
+
 /**
  * Validate a tool input object against the (optional) JSON-schema definition
  * declared on the tool entry. Returns `{ ok: true }` if the input is valid (or

package/src/stt/types.ts

@@ -30,19 +30,15 @@ export type SttProviderId =
  * Telephony-specific STT capability class.
  *
  * Describes the provider's native audio-ingestion capability when used in
- * a telephony context. This is a **capability classification**, not a direct
- * Twilio strategy selector — the telephony routing resolver
- * (`telephony-stt-routing.ts`) maps capability classes plus catalog routing
- * metadata to concrete Twilio setup strategies (conversation-relay-native
- * vs media-stream-custom).
+ * a telephony context. This is a **capability classification** consumed by
+ * `resolveTelephonySttCapability` (providers/speech-to-text/resolve.ts) —
+ * every supported provider transcribes call audio server-side on the
+ * media-stream transport; this field describes how it ingests that audio.
  *
  * - `"realtime-ws"` — provider offers a WebSocket streaming endpoint suitable
  *   for low-latency telephony audio (e.g. Deepgram live transcription).
  * - `"batch-only"` — provider supports only REST batch transcription as its
- *   native capability. A `batch-only` provider may still participate in
- *   telephony via Twilio-native ConversationRelay (e.g. Google Gemini) or
- *   via the media-stream custom path — the routing strategy is determined
- *   by the catalog's telephony routing metadata, not this field alone.
+ *   native capability; call audio is transcribed in incremental batches.
  * - `"none"` — provider has no telephony support.
  */
 export type TelephonySttMode = "realtime-ws" | "batch-only" | "none";