@vellumai/assistant 0.12.2-staging.5 → 0.12.2-staging.7

package/src/runtime/routes/plugins-routes.ts

@@ -2,7 +2,7 @@
  * Route handlers for the assistant plugins surface.
  *
  * GET    /v1/plugins          — list installed plugins under `<workspaceDir>/plugins/`.
- * GET    /v1/plugins/search   — search the canonical GitHub catalog of installable plugins.
+ * GET    /v1/plugins/search   - search the reviewed catalog of installable plugins.
  * GET    /v1/plugins/:name    — resolve a single plugin's detail view (metadata + README).
  * POST   /v1/plugins/install  — install a plugin by name from the canonical source.
  * DELETE /v1/plugins/:name    — uninstall a plugin from `<workspaceDir>/plugins/<name>/`.
@@ -192,30 +192,47 @@ const pluginsListResponseSchema = z.object({
 });
 
 const pluginMatchSourceSchema = z
-  .object({
-    kind: z.literal("github"),
-    repo: z
-      .string()
-      .describe("`owner/repo` of the external plugin repository."),
-    path: z
-      .string()
-      .optional()
-      .describe(
-        "Directory within the repo, when the plugin is not at the root.",
-      ),
-    ref: z.string().describe("Pinned git ref the plugin is fetched from."),
-  })
-  .describe("Origin of the match: a whitelisted external plugin repository.");
+  .discriminatedUnion("kind", [
+    z.object({
+      kind: z.literal("github"),
+      repo: z
+        .string()
+        .describe("`owner/repo` of the external plugin repository."),
+      path: z
+        .string()
+        .optional()
+        .describe(
+          "Directory within the repo, when the plugin is not at the root.",
+        ),
+      ref: z.string().describe("Pinned git ref the plugin is fetched from."),
+    }),
+    z.object({
+      kind: z.literal("local"),
+      path: z.string().describe("Package key in the assistant bundle."),
+      version: z.string().describe("Bundled package version."),
+    }),
+  ])
+  .describe("Reviewed source of the marketplace entry.");
+
+const mcpPluginIntegrationSchema = z.object({
+  kind: z.literal("mcp"),
+  displayName: z.string(),
+  documentationUrl: z.string(),
+  verifiedAt: z.string(),
+  verification: z.literal("documentation-only"),
+  setup: z.object({
+    mode: z.enum(["oauth", "manual"]),
+    instructions: z.string(),
+  }),
+  logo: z.string(),
+  oauthProvider: z.string().optional(),
+});
 
 const pluginSearchMatchSchema = z.object({
   name: z
     .string()
     .describe("Install name. Matches `assistant plugins install <name>`."),
-  path: z
-    .string()
-    .describe(
-      "Human-readable origin: a `github:owner/repo@ref` locator for the external plugin.",
-    ),
+  path: z.string().describe("Human-readable catalog origin locator."),
   description: z
     .string()
     .optional()
@@ -232,6 +249,7 @@ const pluginSearchMatchSchema = z.object({
     .describe(
       "Marketplace category slug (Skills taxonomy); null when the entry declares none.",
     ),
+  integration: mcpPluginIntegrationSchema.optional(),
   source: pluginMatchSourceSchema,
 });
 
@@ -418,22 +436,20 @@ const fingerprintComparisonSchema = z
   );
 
 const installMetaSourceSchema = z
-  .object({
-    kind: z.string().describe("Source kind. Only `github` is written today."),
-    owner: z.string(),
-    repo: z.string(),
-    path: z
-      .string()
-      .optional()
-      .describe(
-        "Repo-relative directory holding the plugin root; absent = repo root.",
-      ),
-    ref: z
-      .string()
-      .describe(
-        "Ref the install resolved through (the pinned commit SHA for marketplace installs).",
-      ),
-  })
+  .discriminatedUnion("kind", [
+    z.object({
+      kind: z.literal("github"),
+      owner: z.string(),
+      repo: z.string(),
+      path: z.string().optional(),
+      ref: z.string(),
+    }),
+    z.object({
+      kind: z.literal("local"),
+      path: z.string(),
+      version: z.string(),
+    }),
+  ])
   .describe(
     "Source coordinates recorded in the install-time provenance sidecar.",
   );
@@ -489,6 +505,7 @@ const pluginLocalInfoSchema = z
 
 const pluginRemoteInfoSchema = z
   .object({
+    kind: z.literal("local").optional(),
     repo: z
       .string()
       .describe("`owner/repo` of the external plugin repository."),
@@ -517,6 +534,7 @@ const pluginRemoteInfoSchema = z
       .describe(
         "Ref of the canonical repo the marketplace manifest was read from.",
       ),
+    version: z.string().optional().describe("Bundled package version."),
   })
   .describe("The marketplace's current pin and advertised metadata.");
 
@@ -870,7 +888,8 @@ interface PluginMatchView {
   description?: string;
   icon?: string;
   category: string | null;
-  source: { kind: "github"; repo: string; path?: string; ref: string };
+  integration?: PluginSearchMatch["integration"];
+  source: PluginSearchMatch["source"];
 }
 
 /**
@@ -886,12 +905,7 @@ function projectMatch(
     name: m.name,
     path: m.path,
     category: normalizeMarketplaceCategory(m.category, validSlugs),
-    source: {
-      kind: "github",
-      repo: m.source.repo,
-      ref: m.source.ref,
-      ...(m.source.path !== undefined ? { path: m.source.path } : {}),
-    },
+    source: { ...m.source },
   };
   if (m.description !== undefined) {
     view.description = m.description;
@@ -899,6 +913,9 @@ function projectMatch(
   if (m.icon !== undefined) {
     view.icon = m.icon;
   }
+  if (m.integration !== undefined) {
+    view.integration = m.integration;
+  }
   return view;
 }
 
@@ -1276,12 +1293,15 @@ async function handleInstallPlugin({ body = {}, headers }: RouteHandlerArgs) {
         {
           name,
           force,
-          trustedSource: {
-            owner: source.owner,
-            repo: source.repo,
-            rootPath: source.path,
-            ref: source.ref,
-          },
+          trustedSource:
+            source.kind === "local"
+              ? source
+              : {
+                  owner: source.owner,
+                  repo: source.repo,
+                  rootPath: source.path,
+                  ref: source.ref,
+                },
         },
         { fetch: globalThis.fetch.bind(globalThis) },
       );

package/src/schedule/run-script.ts

@@ -1,6 +1,7 @@
 import { buildSanitizedEnv } from "../tools/terminal/safe-env.js";
 import {
   buildShellInvocation,
+  buildShellSpawnFlags,
   terminateProcessTree,
 } from "../util/host-process.js";
 import { getLogger } from "../util/logger.js";
@@ -64,10 +65,9 @@ export async function runScript(
   const shell = buildShellInvocation(command);
   const proc = Bun.spawn([shell.command, ...shell.args], {
     cwd,
-    detached: true,
+    ...buildShellSpawnFlags(),
     stdout: "pipe",
     stderr: "pipe",
-    windowsHide: true,
     env: {
       ...buildSanitizedEnv(),
       // __SCHEDULE_ID lets a saved command find its own dir; __SCHEDULE_RUN_ID

package/src/skills/managed-store.ts

@@ -18,6 +18,7 @@ import { parseFrontmatter } from "../config/skills.js";
 import { deleteSkillCapabilityNode } from "../plugins/defaults/memory/graph/capability-seed.js";
 import { isDeniedBasename } from "../tools/shared/filesystem/path-policy.js";
 import { getLogger } from "../util/logger.js";
+import { isPlainObject } from "../util/object.js";
 import { getWorkspaceDir, getWorkspaceSkillsDir } from "../util/platform.js";
 import { parseFrontmatterFields } from "./frontmatter.js";
 import { writeInstallMeta } from "./install-meta.js";
@@ -212,11 +213,48 @@ interface BuildSkillMarkdownInput {
   name: string;
   description: string;
   bodyMarkdown: string;
+  /**
+   * The five fields the scaffold tool owns. `undefined` leaves whatever
+   * `preserve` carries for that field (nothing, on a create); an empty value
+   * clears it; a value sets it.
+   */
   emoji?: string;
   includes?: string[];
   activationHints?: string[];
   avoidWhen?: string[];
   category?: string;
+  /**
+   * The skill's existing frontmatter, as parsed from disk, for an overwrite.
+   * Every key survives except `name`, `description`, and the five fields
+   * above, so a `platforms` gate, a `display-name`, or custom metadata a
+   * person added by hand is not lost to a call that never mentions it.
+   */
+  preserve?: Record<string, unknown>;
+}
+
+/**
+ * Apply one tool-owned field to the vellum block: an input left `undefined`
+ * keeps the preserved value, an input given but empty (`value` undefined)
+ * clears it, and a value sets it.
+ */
+function setOrClear(
+  target: Record<string, unknown>,
+  key: string,
+  value: unknown,
+  input: unknown,
+): void {
+  if (input === undefined) {
+    return;
+  }
+  if (value === undefined) {
+    delete target[key];
+  } else {
+    target[key] = value;
+  }
+}
+
+function nonEmptyList(list: string[] | undefined): string[] | undefined {
+  return list && list.length > 0 ? list : undefined;
 }
 
 export function buildSkillMarkdown(input: BuildSkillMarkdownInput): string {
@@ -230,40 +268,55 @@ export function buildSkillMarkdown(input: BuildSkillMarkdownInput): string {
   lines.push(`name: "${esc(input.name)}"`);
   lines.push(`description: "${esc(input.description)}"`);
 
-  // Build metadata object matching the format parseFrontmatter expects:
-  // metadata:
-  //   vellum:
-  //     emoji: "..."
-  const vellum: Record<string, unknown> = {};
-  if (input.emoji) {
-    vellum.emoji = input.emoji;
-  }
-  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
+  // Everything but name and description is emitted from one object: the
+  // preserved frontmatter with the tool-owned fields applied over it, under
+  // `metadata.vellum` where parseFrontmatter reads them back (kebab-case for
+  // the two list fields). stringifyYaml quotes and escapes values, so no
   // manual sanitization is needed here.
-  if (input.activationHints && input.activationHints.length > 0) {
-    vellum["activation-hints"] = input.activationHints;
+  const rest: Record<string, unknown> = structuredClone(input.preserve ?? {});
+  delete rest.name;
+  delete rest.description;
+  const metadata = isPlainObject(rest.metadata) ? rest.metadata : {};
+  const vellum = isPlainObject(metadata.vellum) ? metadata.vellum : {};
+  setOrClear(vellum, "emoji", input.emoji?.trim() || undefined, input.emoji);
+  // An emoji at the legacy `metadata.emoji` location wins over an absent
+  // vellum one on read, so a call that states the emoji retires it.
+  if (input.emoji !== undefined) {
+    delete metadata.emoji;
   }
-  if (input.avoidWhen && input.avoidWhen.length > 0) {
-    vellum["avoid-when"] = input.avoidWhen;
+  setOrClear(vellum, "includes", nonEmptyList(input.includes), input.includes);
+  setOrClear(
+    vellum,
+    "activation-hints",
+    nonEmptyList(input.activationHints),
+    input.activationHints,
+  );
+  setOrClear(
+    vellum,
+    "avoid-when",
+    nonEmptyList(input.avoidWhen),
+    input.avoidWhen,
+  );
+  // The web Skills UI buckets skills by this value; a blank one is a clear,
+  // never an empty bucket in the file.
+  setOrClear(
+    vellum,
+    "category",
+    input.category?.trim() || undefined,
+    input.category,
+  );
+  if (Object.keys(vellum).length > 0) {
+    metadata.vellum = vellum;
+  } else {
+    delete metadata.vellum;
   }
-  // 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()) {
-    vellum.category = input.category.trim();
+  if (Object.keys(metadata).length > 0) {
+    rest.metadata = metadata;
+  } else {
+    delete rest.metadata;
   }
-
-  if (Object.keys(vellum).length > 0) {
-    const metadata = { vellum };
-    const yamlBlock = stringifyYaml(metadata, { indent: 2 });
-    lines.push("metadata:");
-    for (const yamlLine of yamlBlock.trimEnd().split("\n")) {
-      lines.push(`  ${yamlLine}`);
-    }
+  if (Object.keys(rest).length > 0) {
+    lines.push(stringifyYaml(rest, { indent: 2 }).trimEnd());
   }
 
   lines.push("---");
@@ -350,7 +403,8 @@ export function createManagedSkill(
   const skillDir = getManagedSkillDir(params.id);
   const skillFilePath = join(skillDir, "SKILL.md");
 
-  if (existsSync(skillFilePath) && !params.overwrite) {
+  const skillExists = existsSync(skillFilePath);
+  if (skillExists && !params.overwrite) {
     return {
       created: false,
       path: skillFilePath,
@@ -358,6 +412,14 @@ export function createManagedSkill(
     };
   }
 
+  // An overwrite replaces the body and patches the frontmatter: a field the
+  // call leaves undefined keeps its current value, an explicit empty value
+  // clears it, and frontmatter the tool does not own passes through. Callers
+  // rarely hold every field (the retrospective sees a skill through a
+  // similarity hit; a user edit is "change step 3"), so a field they do not
+  // pass is kept rather than dropped.
+  const existing = skillExists ? readStoredManagedSkill(params.id) : null;
+
   // Resolve and validate every companion path before any write so an invalid
   // path leaves no partial files behind.
   const companionWrites: Array<{ resolvedPath: string; content: string }> = [];
@@ -413,6 +475,7 @@ export function createManagedSkill(
     activationHints: params.activationHints,
     avoidWhen: params.avoidWhen,
     category: params.category,
+    preserve: existing?.frontmatter,
   });
 
   mkdirSync(skillDir, { recursive: true });
@@ -461,11 +524,13 @@ export function createManagedSkill(
  * `{workspaceDir}` and strips feature-gated sections, and a caller that wrote
  * that output back would bake absolute paths into the skill; and a first line
  * that opens an indented code block must keep its indentation or a copy turns
- * it into prose.
+ * it into prose. `frontmatter` is the whole block as written, for an
+ * overwrite to carry keys through that the typed fields do not cover.
  */
 export interface StoredManagedSkill {
   name: string;
   description: string;
+  frontmatter: Record<string, unknown>;
   emoji?: string;
   includes?: string[];
   activationHints?: string[];
@@ -493,6 +558,7 @@ export function readStoredManagedSkill(
     return {
       name: parsed.name,
       description: parsed.description,
+      frontmatter: raw.fields,
       emoji: parsed.emoji,
       includes: parsed.includes,
       activationHints: parsed.activationHints,

package/src/tools/host-terminal/host-shell.ts

@@ -23,8 +23,10 @@ import { conversationRevealNonce } from "../../runtime/reveal-nonce.js";
 import { redactSecrets } from "../../security/secret-scanner.js";
 import {
   buildShellInvocation,
+  buildShellSpawnFlags,
   prependUniquePathEntries,
   terminateProcessTree,
+  watchShellProcessStart,
 } from "../../util/host-process.js";
 import { getLogger } from "../../util/logger.js";
 import type { CompletedBackgroundTool } from "../background-tool-registry.js";
@@ -455,9 +457,9 @@ export const hostShellTool = {
         cwd: workingDir,
         env: hostEnv,
         stdio: ["ignore", "pipe", "pipe"],
-        detached: true,
-        windowsHide: true,
+        ...buildShellSpawnFlags(),
       });
+      const launch = watchShellProcessStart(child);
 
       const collector = attachBoundedStdio(child);
       let timedOut = false;
@@ -483,7 +485,9 @@ export const hostShellTool = {
         }
         completed = true;
         clearTimeout(timer);
-        const result = collector.format(code, timedOut, timeoutSec);
+        const result = collector.format(code, timedOut, timeoutSec, {
+          started: launch.didStart(),
+        });
         // Cancel takes precedence over the SIGKILL-induced error result.
         const status = aborted
           ? "cancelled"
@@ -629,9 +633,9 @@ export const hostShellTool = {
         cwd: workingDir,
         env: hostEnv,
         stdio: ["ignore", "pipe", "pipe"],
-        detached: true,
-        windowsHide: true,
+        ...buildShellSpawnFlags(),
       });
+      const launch = watchShellProcessStart(child);
       const collector = attachBoundedStdio(child, {
         onOutput: context.onOutput,
       });
@@ -657,7 +661,9 @@ export const hostShellTool = {
         clearTimeout(timer);
         context.signal?.removeEventListener("abort", onAbort);
 
-        const result = collector.format(code, timedOut, timeoutSec);
+        const result = collector.format(code, timedOut, timeoutSec, {
+          started: launch.didStart(),
+        });
 
         resolve({
           content: result.content,

package/src/tools/shared/filesystem/file-ops-service.ts

@@ -4,6 +4,7 @@ import { dirname, join } from "node:path";
 import { minimatch } from "minimatch";
 
 import { ensureDir, pathExists } from "../../../util/fs.js";
+import { surrogateSafeWindow } from "../../../util/unicode.js";
 import { isAbortLikeError } from "../abort.js";
 import { applyEdit } from "./edit-engine.js";
 import * as Err from "./errors.js";
@@ -102,37 +103,6 @@ function truncationNotice(
   return `\n\n[Truncated: characters ${start}-${end} of ${totalChars}. Read on with start_index=${end}.]`;
 }
 
-const isHighSurrogate = (code: number): boolean =>
-  code >= 0xd800 && code <= 0xdbff;
-const isLowSurrogate = (code: number): boolean =>
-  code >= 0xdc00 && code <= 0xdfff;
-
-/**
- * Character window that never splits a surrogate pair. A split leaves a lone
- * half at each edge, and each encodes to U+FFFD, so the character is lost from
- * both this window and the next one paged in after it.
- */
-export function surrogateSafeWindow(
-  total: number,
-  charCodeAt: (index: number) => number,
-  requestedStart: number,
-  maxChars: number,
-): { start: number; end: number } {
-  let start = Math.max(0, Math.min(requestedStart, total));
-  if (start > 0 && start < total && isLowSurrogate(charCodeAt(start))) {
-    start -= 1;
-  }
-
-  let end = Math.min(total, start + maxChars);
-  if (end > start && end < total && isHighSurrogate(charCodeAt(end - 1))) {
-    // Backing off would empty a one-character window, which stalls paging on
-    // the same offset, so take the whole pair instead.
-    end = end - 1 > start ? end - 1 : Math.min(total, end + 1);
-  }
-
-  return { start, end };
-}
-
 export class FileSystemOps {
   private policy: PathPolicy;
   private sizeLimit: number | undefined;

package/src/tools/shared/shell-output.test.ts

@@ -7,6 +7,7 @@ import {
   formatShellOutput,
   MAX_OUTPUT_LENGTH,
   OUTPUT_TRUNCATED_TAG,
+  SHELL_DID_NOT_START_MESSAGE,
 } from "./shell-output.js";
 
 describe("BoundedStdioCollector", () => {
@@ -85,6 +86,15 @@ describe("attachBoundedStdio", () => {
   });
 });
 
+describe("formatShellOutput launch start", () => {
+  test("does not report command_completed when the process never started", () => {
+    const result = formatShellOutput("", "", 0, false, 120, { started: false });
+    expect(result.isError).toBe(true);
+    expect(result.content).toBe(SHELL_DID_NOT_START_MESSAGE);
+    expect(result.content).not.toContain("<command_completed />");
+  });
+});
+
 describe("formatShellOutput truncation", () => {
   test("truncates an already-materialized oversized string without a file path", () => {
     const longOutput = "x".repeat(30_000);

package/src/tools/shared/shell-output.ts

@@ -4,6 +4,9 @@ export const MAX_OUTPUT_LENGTH = 20_000;
 
 export const OUTPUT_TRUNCATED_TAG = `<output_truncated limit="20K" />`;
 
+export const SHELL_DID_NOT_START_MESSAGE =
+  "Error: the shell command did not start. No process was created, so the command did not run.";
+
 export interface ShellOutputResult {
   content: string;
   status: string | undefined;
@@ -31,8 +34,16 @@ export function formatShellOutput(
   code: number | null,
   timedOut: boolean,
   timeoutSec: number,
-  options?: { truncated?: boolean },
+  options?: { truncated?: boolean; started?: boolean },
 ): ShellOutputResult {
+  if (options?.started === false) {
+    return {
+      content: SHELL_DID_NOT_START_MESSAGE,
+      status: undefined,
+      isError: true,
+    };
+  }
+
   let output = stdout;
   if (stderr) {
     output += (output ? "\n" : "") + stderr;
@@ -137,6 +148,7 @@ export class BoundedStdioCollector {
     code: number | null,
     timedOut: boolean,
     timeoutSec: number,
+    options?: { started?: boolean },
   ): ShellOutputResult {
     return formatShellOutput(
       Buffer.concat(this.stdoutParts).toString(),
@@ -144,7 +156,7 @@ export class BoundedStdioCollector {
       code,
       timedOut,
       timeoutSec,
-      { truncated: this.truncated },
+      { truncated: this.truncated, started: options?.started },
     );
   }
 }

package/src/tools/skills/find-similar-skills.test.ts

@@ -257,6 +257,7 @@ describe("find_similar_skills: current skill for a refinable hit", () => {
     "weekly-export": {
       name: "Weekly Report Export",
       description: "Export the weekly usage report",
+      frontmatter: {},
       emoji: "📊",
       category: "productivity",
       includes: ["csv-basics"],
@@ -267,11 +268,13 @@ describe("find_similar_skills: current skill for a refinable hit", () => {
     "user-skill": {
       name: "User Skill",
       description: "A person wrote this",
+      frontmatter: {},
       body: "Do the user's thing.",
     },
     "clean-disk": {
       name: "Clean Disk",
       description: "Free up disk space",
+      frontmatter: {},
       body: "Delete caches.",
     },
   };

package/src/tools/skills/resolve-execute-invocation.ts

@@ -0,0 +1,24 @@
+import { getTool } from "../registry.js";
+import { resolveToolInvocationAlias } from "../tool-name-aliases.js";
+import {
+  recoverSkillExecuteEnvelope,
+  resolveSkillExecuteInput,
+} from "./execute.js";
+
+export function resolveSkillExecuteInvocation(
+  input: Record<string, unknown>,
+  allowedToolNames?: ReadonlySet<string>,
+): { name: string; input: Record<string, unknown> } {
+  const envelope = recoverSkillExecuteEnvelope(input);
+  const rawToolName = typeof envelope.tool === "string" ? envelope.tool : "";
+  const innerSchema = rawToolName
+    ? getTool(rawToolName)?.input_schema
+    : undefined;
+  const rawToolInput = resolveSkillExecuteInput(envelope, innerSchema);
+
+  return resolveToolInvocationAlias(
+    rawToolName,
+    { ...rawToolInput },
+    allowedToolNames,
+  );
+}

package/src/tools/skills/sandbox-runner.ts

@@ -7,9 +7,12 @@ import { conversationRevealNonce } from "../../runtime/reveal-nonce.js";
 import { computeSkillVersionHash } from "../../skills/version-hash.js";
 import {
   buildShellInvocation,
+  buildShellSpawnFlags,
   terminateProcessTree,
+  watchShellProcessStart,
 } from "../../util/host-process.js";
 import { safeStringSlice } from "../../util/unicode.js";
+import { SHELL_DID_NOT_START_MESSAGE } from "../shared/shell-output.js";
 import { buildSanitizedEnv } from "../terminal/safe-env.js";
 import type { ToolContext, ToolExecutionResult } from "../types.js";
 
@@ -160,9 +163,9 @@ function spawnRunner(
       cwd: runDir,
       env,
       stdio: ["ignore", "pipe", "pipe"],
-      detached: true,
-      windowsHide: true,
+      ...buildShellSpawnFlags(),
     });
+    const launch = watchShellProcessStart(child);
 
     const timer = setTimeout(() => {
       timedOut = true;
@@ -188,6 +191,14 @@ function spawnRunner(
       clearTimeout(timer);
       context.signal?.removeEventListener("abort", onAbort);
 
+      if (!launch.didStart()) {
+        resolve({
+          content: `Failed to spawn skill tool script "${executorPath}": ${SHELL_DID_NOT_START_MESSAGE}`,
+          isError: true,
+        });
+        return;
+      }
+
       if (timedOut) {
         resolve({
           content: `Skill tool script "${executorPath}" timed out after ${timeoutMs}ms`,