@vellumai/assistant 0.12.2-staging.1 → 0.12.2-staging.3

package/src/tools/ui-surface/channel-variants.ts

@@ -1,68 +1,19 @@
 /**
- * Per-conversation wire projections of the UI surface tool definitions.
+ * Conversation-stable wire projections of the UI surface tool definitions.
  *
- * Slack renders exactly one surface — the task_progress card (everything else
- * is rejected at execution; see `isSlackTaskProgressUiException` in
- * `daemon/conversation-surfaces.ts`) — so Slack conversations get a `ui_show`
- * variant documenting only that shape instead of the full multi-surface docs.
- * Activation-rail conversations additionally get the `activation_moment`
- * telemetry param, which no other conversation pays schema tokens for (the
- * emit path is gated on `isActivationSession` regardless).
+ * `ui_show`, `ui_update`, and `ui_dismiss` keep one definition across every
+ * channel and across live vs clientless turns. Channel renderers enforce the
+ * surfaces they can display at execution. Clientless calls persist surface
+ * content for the next capable client that opens the conversation.
  *
- * Projection contract: shared definition objects are never mutated (variants
- * are module-level constants swapped in via spread-copy), and the projected
- * set is a pure function of per-conversation-stable state, so a
- * conversation's tools+system prompt-cache prefix stays stable across turns.
+ * `activation_moment` is the remaining schema projection. It applies only to
+ * activation-rail conversations, whose marker is written before the first
+ * tool resolution, so the extra property is stable for that conversation's
+ * lifetime. It must not vary by channel or turn presence.
  */
 
 import type { ToolDefinition } from "../../providers/types.js";
 import { ACTIVATION_MOMENT_PARAMS } from "../../telemetry/activation-funnel.js";
-import { TASK_PROGRESS_TEMPLATE_SHAPE } from "./surface-shape-docs.js";
-
-const SLACK_UI_SHOW_DESCRIPTION = `Show a live task-progress card for the current work — the only surface this channel renders. data: { template: "task_progress", templateData: ${TASK_PROGRESS_TEMPLATE_SHAPE} }. Show it early on multi-step turns and advance step statuses via ui_update as work progresses.`;
-
-const SLACK_UI_SHOW_INPUT_SCHEMA = {
-  type: "object",
-  properties: {
-    surface_type: {
-      type: "string",
-      enum: ["card"],
-      description: "Always card on this channel",
-    },
-    title: {
-      type: "string",
-      description: "Optional surface title",
-    },
-    data: {
-      type: "object",
-      description:
-        'Card data: { template: "task_progress", templateData: { title, status, steps } }',
-    },
-  },
-  required: ["surface_type", "data"],
-};
-
-/**
- * Swap UI surface tool definitions for channel-appropriate variants. Returns
- * the input array unchanged (same identity) for channels without a variant.
- */
-export function projectUiToolsForChannel(
-  definitions: ToolDefinition[],
-  channel: string | undefined,
-): ToolDefinition[] {
-  if (channel !== "slack") {
-    return definitions;
-  }
-  return definitions.map((def) =>
-    def.name === "ui_show"
-      ? {
-          ...def,
-          description: SLACK_UI_SHOW_DESCRIPTION,
-          input_schema: SLACK_UI_SHOW_INPUT_SCHEMA,
-        }
-      : def,
-  );
-}
 
 const ACTIVATION_MOMENT_PROPERTY = {
   type: "string",
@@ -73,7 +24,7 @@ const ACTIVATION_MOMENT_PROPERTY = {
 
 /**
  * Add the optional `activation_moment` param to ui_show's schema. Applied
- * only for activation-rail conversations (`isActivationSession`) — the rail
+ * only for activation-rail conversations (`isActivationSession`). The rail
  * bootstrap prompt instructs the tagging, and the daemon's emit path reads
  * the tag from tool input independently of this schema.
  */

package/src/util/abort-reasons.ts

@@ -21,7 +21,18 @@ export type AbortReasonKind =
   /** A signal-file cancel was written by an out-of-process caller (CLI, hook). */
   | "signal_cancel"
   /** Voice session bridge aborted the conversation (turn supersession, call end). */
-  | "voice_session_aborted";
+  | "voice_session_aborted"
+  /**
+   * One spoken progress update ran out of its generation budget.
+   *
+   * Distinct from {@link "voice_session_aborted"} because nothing was aborted
+   * but the update itself: the call is still up, the turn is still running,
+   * and the only consequence is that this beat goes unspoken. Sharing the
+   * session-abort kind made a narrator that had gone fail-open read in the
+   * logs as a session dying over and over, which is the opposite of what the
+   * line means.
+   */
+  | "voice_progress_narration_timeout";
 
 const ABORT_REASON_TAG = "__vellumAbortReason" as const;
 

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/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/desktop/desktop-feature.test.ts

@@ -1,18 +0,0 @@
-import { describe, expect, test } from "bun:test";
-
-import { setOverridesForTesting } from "../__tests__/feature-flag-test-helpers.js";
-import type { AssistantConfig } from "../config/schema.js";
-import { isAssistantDesktopEnabled } from "./desktop-feature.js";
-
-describe("isAssistantDesktopEnabled", () => {
-  const config = {} as AssistantConfig;
-
-  test("needs both the flag and a containerized runtime", () => {
-    setOverridesForTesting({ "assistant-desktop": true });
-    expect(isAssistantDesktopEnabled(config, true)).toBe(true);
-    expect(isAssistantDesktopEnabled(config, false)).toBe(false);
-
-    setOverridesForTesting({ "assistant-desktop": false });
-    expect(isAssistantDesktopEnabled(config, true)).toBe(false);
-  });
-});

package/src/desktop/desktop-feature.ts

@@ -1,19 +0,0 @@
-import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
-import { getIsContainerized } from "../config/env-registry.js";
-import type { AssistantConfig } from "../config/schema.js";
-
-const ASSISTANT_DESKTOP_FLAG = "assistant-desktop" as const;
-
-/**
- * Whether this daemon serves `/v1/desktop/stream`: the `assistant-desktop` flag
- * plus a containerized runtime where desktop components can be installed.
- */
-export function isAssistantDesktopEnabled(
-  config: AssistantConfig,
-  containerized: boolean = getIsContainerized(),
-): boolean {
-  return (
-    containerized &&
-    isAssistantFeatureFlagEnabled(ASSISTANT_DESKTOP_FLAG, config)
-  );
-}