@vellumai/assistant 0.12.1 → 0.12.2-dev.202609162314.7778bc8

package/src/util/plugin-manifest.ts

@@ -0,0 +1,203 @@
+/**
+ * Resolve the manifest that identifies an installed plugin.
+ *
+ * `package.json` is the primary manifest for Vellum plugins. A root
+ * `plugin.json` is selected only when `package.json` is absent, so a legacy
+ * plugin can carry another ecosystem's `plugin.json` without being
+ * reclassified.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { z } from "zod";
+
+export const LEGACY_PLUGIN_MANIFEST = "package.json";
+export const STANDARD_PLUGIN_MANIFEST = "plugin.json";
+export const AGENT_PLUGINS_MANIFEST_SCHEMA_URL =
+  "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+
+const PluginNameSchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[a-z0-9](?!.*(?:--|\.\.))[a-z0-9.-]*[a-z0-9]$|^[a-z0-9]$/);
+
+const LegacyPluginManifestSchema = z
+  .object({
+    name: z.string().min(1),
+    version: z.string().optional(),
+    description: z.string().min(1).optional(),
+    homepage: z.string().optional(),
+    license: z.unknown().optional(),
+    peerDependencies: z.record(z.string(), z.string()).optional(),
+    credentialKeyPatterns: z.unknown().optional(),
+    displayName: z.string().min(1).optional(),
+    icon: z.string().min(1).optional(),
+  })
+  .passthrough();
+
+const StandardPluginManifestSchema = z
+  .object({
+    $schema: z.literal(AGENT_PLUGINS_MANIFEST_SCHEMA_URL),
+    name: PluginNameSchema,
+    version: z.string().optional(),
+    description: z.string().optional(),
+    author: z
+      .object({
+        name: z.string().optional(),
+        email: z.string().optional(),
+        url: z.string().optional(),
+      })
+      .strict()
+      .optional(),
+    homepage: z.string().optional(),
+    repository: z.string().optional(),
+    license: z.string().optional(),
+    keywords: z.array(z.string()).optional(),
+    // The core specification says a non-object extensions value is reported
+    // and ignored rather than rejecting the plugin. This host does not consume
+    // a standard extension namespace here, so keep it opaque.
+    extensions: z.unknown().optional(),
+  })
+  // Unknown core fields are reported-and-ignored by the specification. The
+  // loader does not assign them semantics, so passthrough preserves that
+  // non-fatal behavior without copying them into runtime metadata.
+  .passthrough();
+
+export type PluginManifestSource =
+  | typeof LEGACY_PLUGIN_MANIFEST
+  | typeof STANDARD_PLUGIN_MANIFEST;
+
+export interface ResolvedPluginManifest {
+  readonly source: PluginManifestSource;
+  readonly name: string;
+  readonly version?: string;
+  readonly description?: string;
+  readonly homepage?: string;
+  readonly license?: unknown;
+  /** Parsed selected manifest, retained for Vellum-specific legacy fields. */
+  readonly raw: Record<string, unknown>;
+}
+
+export type PluginManifestInstallAction = "keep" | "synthesize-legacy";
+
+export class PluginManifestError extends Error {
+  constructor(
+    readonly pluginDir: string,
+    readonly source: PluginManifestSource | null,
+    message: string,
+    readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = "PluginManifestError";
+  }
+}
+
+/** True when the directory carries either supported root manifest. */
+export function hasPluginManifest(pluginDir: string): boolean {
+  return (
+    existsSync(join(pluginDir, LEGACY_PLUGIN_MANIFEST)) ||
+    existsSync(join(pluginDir, STANDARD_PLUGIN_MANIFEST))
+  );
+}
+
+/**
+ * Decide whether an installed artifact needs the compatibility `package.json`.
+ *
+ * A `package.json` file is always preserved. A root `plugin.json`
+ * claims the Agent Plugins format only when it names the supported schema. A
+ * claimed standard manifest is validated before install; other `plugin.json`
+ * files remain foreign metadata beside the synthesized compatibility manifest.
+ */
+export function getPluginManifestInstallAction(
+  pluginDir: string,
+): PluginManifestInstallAction {
+  if (existsSync(join(pluginDir, LEGACY_PLUGIN_MANIFEST))) {
+    return "keep";
+  }
+
+  const standardPath = join(pluginDir, STANDARD_PLUGIN_MANIFEST);
+  if (!existsSync(standardPath)) {
+    return "synthesize-legacy";
+  }
+
+  let json: unknown;
+  try {
+    json = JSON.parse(readFileSync(standardPath, "utf8"));
+  } catch {
+    return "synthesize-legacy";
+  }
+
+  if (
+    typeof json !== "object" ||
+    json === null ||
+    Array.isArray(json) ||
+    (json as Record<string, unknown>).$schema !==
+      AGENT_PLUGINS_MANIFEST_SCHEMA_URL
+  ) {
+    return "synthesize-legacy";
+  }
+
+  readPluginManifest(pluginDir);
+  return "keep";
+}
+
+/**
+ * Read and validate the selected root manifest.
+ *
+ * Selection is deterministic: `package.json` wins when present, including
+ * when it is malformed. The loader never falls through
+ * from a selected malformed legacy manifest to `plugin.json`.
+ */
+export function readPluginManifest(pluginDir: string): ResolvedPluginManifest {
+  const source = existsSync(join(pluginDir, LEGACY_PLUGIN_MANIFEST))
+    ? LEGACY_PLUGIN_MANIFEST
+    : existsSync(join(pluginDir, STANDARD_PLUGIN_MANIFEST))
+      ? STANDARD_PLUGIN_MANIFEST
+      : null;
+  if (source === null) {
+    throw new PluginManifestError(
+      pluginDir,
+      null,
+      `plugin at ${pluginDir} is missing package.json and plugin.json`,
+    );
+  }
+
+  const path = join(pluginDir, source);
+  let json: unknown;
+  try {
+    json = JSON.parse(readFileSync(path, "utf8"));
+  } catch (cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    throw new PluginManifestError(
+      pluginDir,
+      source,
+      `${source} at ${pluginDir} could not be read or parsed: ${reason}`,
+      cause,
+    );
+  }
+
+  const parsed =
+    source === LEGACY_PLUGIN_MANIFEST
+      ? LegacyPluginManifestSchema.safeParse(json)
+      : StandardPluginManifestSchema.safeParse(json);
+  if (!parsed.success) {
+    throw new PluginManifestError(
+      pluginDir,
+      source,
+      `${source} at ${pluginDir} failed schema validation: ${parsed.error.message}`,
+      parsed.error,
+    );
+  }
+
+  return {
+    source,
+    name: parsed.data.name,
+    version: parsed.data.version,
+    description: parsed.data.description,
+    homepage: parsed.data.homepage,
+    license: parsed.data.license,
+    raw: parsed.data,
+  };
+}

package/src/util/unicode.ts

@@ -67,6 +67,35 @@ export function safeStringSlice(
   return str.slice(safeStart, safeEnd);
 }
 
+/**
+ * A `[start, end)` character window of at most `maxChars` code units that
+ * never splits a surrogate pair, for paging through text by offset. 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. `charCodeAt` reads the underlying text so a caller need not hold it as
+ * one string.
+ */
+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 };
+}
+
 /**
  * Replace every orphaned UTF-16 surrogate in `str` with U+FFFD
  * (REPLACEMENT CHARACTER).
@@ -126,6 +155,15 @@ export interface DeepSanitizeResult<T> {
   fixedStringCount: number;
 }
 
+export interface DeepSanitizeOptions {
+  /**
+   * Skip a plain-object property entirely: its value is neither scanned nor
+   * copied. For fields known to hold ASCII (base64 payloads), scanning is
+   * pure cost.
+   */
+  skipKey?: (key: string, parent: Record<string, unknown>) => boolean;
+}
+
 /**
  * Recursively walk arrays and plain objects, replacing orphaned surrogates in
  * every string value. Non-plain objects (class instances, Date, Buffer, Map,
@@ -136,8 +174,10 @@ export interface DeepSanitizeResult<T> {
  */
 export function stripOrphanedSurrogatesDeep<T>(
   input: T,
+  options: DeepSanitizeOptions = {},
 ): DeepSanitizeResult<T> {
   let fixedStringCount = 0;
+  const { skipKey } = options;
 
   const walk = (value: unknown): { value: unknown; changed: boolean } => {
     if (typeof value === "string") {
@@ -178,7 +218,10 @@ export function stripOrphanedSurrogatesDeep<T>(
       let next: Record<string, unknown> | null = null;
       for (let i = 0; i < keys.length; i++) {
         const key = keys[i]!;
-        const result = walk(source[key]);
+        const result =
+          skipKey?.(key, source) === true
+            ? { value: source[key], changed: false }
+            : walk(source[key]);
         if (result.changed && next === null) {
           next = {};
           for (let j = 0; j < i; j++) {

package/src/watch/watch-retro.ts

@@ -61,14 +61,12 @@ const WATCH_RETRO_WAKE_SOURCE = "watch-retro";
  * under the `watch_retro` template, which the client draws as a paged card: the
  * record on the first page, one question per page after it.
  *
- * **The daemon appends the card; the model never reaches `ui_show`.** This wake
- * is `clientless`, and `conversation-tool-setup` gates the whole `ui_surface`
- * family on a client being present, so `ui_show` is absent from this turn's
- * tool set rather than merely denied. A retrospective told to call it can only
- * report that it cannot. `watch_retro_report` is an ordinary tool and passes
- * that gate, and the surface is appended here, the way the memory
- * retrospective's `skill_card` is appended by the daemon rather than requested
- * by the model.
+ * **The daemon appends the card; the model calls `watch_retro_report`.** This
+ * wake is `clientless`. `ui_show` stays on the wire so background surfaces can
+ * persist, but this flow still reports through `watch_retro_report` so the
+ * daemon can append the card after the turn ends. The memory retrospective's
+ * `skill_card` is appended the same way: the daemon writes the surface, the
+ * model does not request it.
  *
  * **The append waits for the turn to end.** A `ui_surface` row written mid-turn
  * can land between a persisted `tool_use` and its `tool_result`, an ordering

package/src/watch/watch-timeline.ts

@@ -366,8 +366,8 @@ export function appendNarration(
  * timeline of a session where observation stalled is simply a sparser one.
  *
  * The screenshot is stored only when `attachScreenshot` asks for it, and
- * carrying one is not asking. The host captures a screenshot on every observe
- * with no opt-out, so an observation always has pixels available and a policy
+ * carrying one is not asking. Watch requests a screenshot on every observe, so
+ * an observation normally has pixels available and a policy
  * of "store what arrives" is a policy of storing every frame. Which frames are
  * worth an image is a cadence decision, and it belongs to the caller driving
  * the session rather than to the row writer.

package/src/workflows/run-manager.ts

@@ -33,6 +33,7 @@ import type { TrustContext } from "../daemon/trust-context-types.js";
 import { wakeAgentForOpportunity } from "../runtime/agent-wake.js";
 import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import { getLogger } from "../util/logger.js";
+import { safeStringSlice } from "../util/unicode.js";
 import type { CapabilityManifest } from "./capabilities.js";
 import {
   normalizeCapabilityManifest,
@@ -611,7 +612,7 @@ function truncateForSummary(s: string, runId: string): string {
   }
   const omitted = s.length - MAX_SUMMARY_RESULT_CHARS;
   return (
-    `${s.slice(0, MAX_SUMMARY_RESULT_CHARS)}… ` +
+    `${safeStringSlice(s, 0, MAX_SUMMARY_RESULT_CHARS)}… ` +
     `[truncated ${omitted} chars — fetch the full result with manage_workflows ` +
     `{ action: "get_result", run_id: "${runId}" }]`
   );

package/src/workspace/git-porcelain.ts

@@ -0,0 +1,66 @@
+/**
+ * NUL-terminated `git status --porcelain -z` parsing.
+ *
+ * Status reporting and batched staging share this parser so rename/copy
+ * origin paths cannot drift between the two readers.
+ */
+
+export interface PorcelainEntry {
+  /** Two-character XY status from porcelain v1. */
+  status: string;
+  /** Path git reports for this record (the destination for rename/copy). */
+  path: string;
+  /** Pre-rename/copy path. Present when the record is a rename or copy. */
+  origin?: string;
+}
+
+/**
+ * Parse NUL-terminated `git status --porcelain -z` output into status/path
+ * records. NUL termination is required so paths with special characters
+ * (non-ASCII, quotes, newlines) arrive verbatim instead of C-style quoted.
+ *
+ * A rename/copy record is followed by a bare origin-path entry, captured on
+ * {@link PorcelainEntry.origin}.
+ */
+export function parsePorcelainZ(stdout: string): PorcelainEntry[] {
+  const entries = stdout.split("\0");
+  const parsed: PorcelainEntry[] = [];
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i] ?? "";
+    if (entry.length < 4) {
+      continue;
+    }
+    const status = entry.substring(0, 2);
+    const path = entry.substring(3);
+    if (status[0] === "R" || status[0] === "C") {
+      i++;
+      const origin = entries[i];
+      if (origin && origin.length > 0) {
+        parsed.push({ status, path, origin });
+        continue;
+      }
+    }
+    parsed.push({ status, path });
+  }
+  return parsed;
+}
+
+/**
+ * Every path git status knows about, including rename/copy origins.
+ * Origins still need to be staged so a deletion is not left behind when a
+ * rename is split across add batches.
+ */
+export function collectDirtyPathsFromPorcelain(stdout: string): string[] {
+  const paths: string[] = [];
+  const seen = new Set<string>();
+  for (const entry of parsePorcelainZ(stdout)) {
+    for (const path of [entry.path, entry.origin]) {
+      if (!path || seen.has(path)) {
+        continue;
+      }
+      seen.add(path);
+      paths.push(path);
+    }
+  }
+  return paths;
+}

package/src/workspace/git-service.ts

@@ -17,6 +17,10 @@ import { getLogger } from "../util/logger.js";
 import { Mutex } from "../util/mutex.js";
 import { addToPathEnv, getExtraToolPathDirs } from "../util/platform.js";
 import { PromiseGuard } from "../util/promise-guard.js";
+import {
+  collectDirtyPathsFromPorcelain,
+  parsePorcelainZ,
+} from "./git-porcelain.js";
 
 const execFileAsync = promisify(execFile);
 const log = getLogger("workspace-git");
@@ -51,7 +55,7 @@ function cleanGitEnv(workspaceDir: string): Record<string, string> {
  * Patterns excluded from workspace git tracking.
  * These are written to .gitignore on init and appended to existing .gitignore files.
  */
-const WORKSPACE_GITIGNORE_RULES = [
+export const WORKSPACE_GITIGNORE_RULES = [
   // Runtime state directories
   "data/db/",
   "data/qdrant/",
@@ -226,59 +230,6 @@ done
 exit 0
 `;
 
-/**
- * Parse NUL-terminated `git status --porcelain -z` output into status/path
- * pairs. NUL termination is required so paths with special characters
- * (non-ASCII, quotes, newlines) arrive verbatim instead of C-style quoted.
- * A rename/copy record is followed by a bare origin-path entry, which is
- * skipped.
- */
-function parsePorcelainZ(
-  stdout: string,
-): Array<{ status: string; path: string }> {
-  const entries = stdout.split("\0");
-  const parsed: Array<{ status: string; path: string }> = [];
-  for (let i = 0; i < entries.length; i++) {
-    const entry = entries[i] ?? "";
-    if (entry.length < 4) {
-      continue;
-    }
-    const status = entry.substring(0, 2);
-    parsed.push({ status, path: entry.substring(3) });
-    if (status[0] === "R" || status[0] === "C") {
-      i++;
-    }
-  }
-  return parsed;
-}
-
-/**
- * Every path git status knows about, including rename/copy origins.
- * Origins are skipped by {@link parsePorcelainZ} (they have no status
- * prefix) but still need to be staged so a deletion is not left behind
- * when a rename is split across add batches.
- */
-function collectDirtyPathsFromPorcelain(stdout: string): string[] {
-  const entries = stdout.split("\0");
-  const paths: string[] = [];
-  for (let i = 0; i < entries.length; i++) {
-    const entry = entries[i] ?? "";
-    if (entry.length < 4) {
-      continue;
-    }
-    const status = entry.substring(0, 2);
-    paths.push(entry.substring(3));
-    if (status[0] === "R" || status[0] === "C") {
-      i++;
-      const origin = entries[i];
-      if (origin && origin.length > 0) {
-        paths.push(origin);
-      }
-    }
-  }
-  return paths;
-}
-
 /** Properties added by Node's child_process errors. */
 interface ExecError extends Error {
   killed?: boolean;
@@ -433,7 +384,7 @@ export class WorkspaceGitService {
    *
    * This method is always called inside the mutex, so no git operation from
    * our code can be concurrently holding the lock. However, an external git
-   * process (user running `git add`, IDE tooling, etc.) could legitimately
+   * git process (user running `git add`, IDE tooling, etc.) could legitimately
    * hold the lock. We use `lsof` to check — if any process has the file
    * open, we leave it alone. If no process holds it, it's stale (crashed
    * process) and safe to remove.