@vellumai/assistant 0.11.4 → 0.11.5-staging.1

package/src/daemon/unsendable-image-notice.ts

@@ -0,0 +1,76 @@
+/**
+ * Transcript notice for images a turn cannot show the model.
+ *
+ * Providers accept exactly four image formats (PNG, JPEG, GIF, WebP), so an
+ * attachment whose bytes are anything else (a corrupt payload, or a HEIC/AVIF
+ * file carrying a `.png` name) is dropped at the provider send boundary by
+ * `resolveMediaReferences`. Dropping is what keeps the rest of the turn alive,
+ * but on its own it is silent: the user sees their image in the transcript and
+ * a reply that ignores it. The card names the files, so the removal is visible
+ * and actionable (convert and re-attach) instead of a mystery.
+ */
+
+import { isUnsendableImageSource } from "../providers/media-resolve.js";
+import type { MediaSource } from "../providers/types.js";
+import { persistSystemCard } from "../runtime/routes/canned-message-complete.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("unsendable-image-notice");
+
+/** An image attachment of a persisted message, as the card check sees it. */
+export interface AttachedImage {
+  filename: string;
+  source: MediaSource;
+}
+
+/** The attachments the send boundary will drop, by filename. */
+export function unsendableImageFilenames(images: AttachedImage[]): string[] {
+  return images
+    .filter((image) => isUnsendableImageSource(image.source))
+    .map((image) => image.filename);
+}
+
+/** Transcript copy for the images this message cannot send to the model. */
+export function unsendableImageCardText(filenames: string[]): string {
+  const names = filenames.join(", ");
+  return filenames.length === 1
+    ? `${names} was not sent to the model: the file is not a PNG, JPEG, GIF, or WebP image. Convert it and attach it again to include it.`
+    : `${names} were not sent to the model: the files are not PNG, JPEG, GIF, or WebP images. Convert them and attach them again to include them.`;
+}
+
+/**
+ * Post a card naming the attachments of a just-persisted message that the send
+ * boundary will drop, or do nothing when every attachment is readable.
+ *
+ * The card is non-terminal: it rides the messages-changed invalidation without
+ * a `message_complete`, so posting it while the turn it describes is in flight
+ * leaves that turn's streaming state untouched. Failures are logged and
+ * swallowed: the turn is already usable without the notice, and losing the
+ * user's whole message to a card write is a worse outcome than losing the card.
+ */
+export async function postUnsendableImageNotice(
+  conversationId: string,
+  images: AttachedImage[],
+): Promise<void> {
+  const filenames = unsendableImageFilenames(images);
+  if (filenames.length === 0) {
+    return;
+  }
+  log.warn(
+    { conversationId, filenames },
+    "User attachments are not a provider-readable image format; posting notice",
+  );
+  try {
+    await persistSystemCard({
+      conversationId,
+      text: unsendableImageCardText(filenames),
+      metadata: { unsendableImageFilenames: filenames },
+      endsTurn: false,
+    });
+  } catch (err) {
+    log.error(
+      { conversationId, err },
+      "Failed to post unsendable-image notice",
+    );
+  }
+}

package/src/hooks/registry.ts

@@ -11,13 +11,16 @@
  * boot, plus the user-land lookup that walks discovered plugin names from
  * the plugin cache.
  *
- * {@link getHooksFor} combines both sources: in-process hooks from this
- * registry (filtered by `isPluginDisabled` at read time) and user-land hooks
- * from the plugin cache. The read-time filtering is what makes `assistant
- * plugins disable default-*` take effect immediately in a running assistant:
- * the hooks stay registered but are filtered out on the next turn.
+ * {@link getHooksFor} and {@link getUserHooksFor} both resolve through
+ * {@link getUserHookEntriesFor}, which prepends in-process default-plugin
+ * hooks from this registry (filtered by `isPluginDisabled` at read time)
+ * ahead of user-land hooks from the plugin cache. The read-time filtering
+ * is what makes `assistant plugins disable default-*` take effect immediately
+ * in a running assistant: the hooks stay registered but are filtered out on
+ * the next turn.
  */
 
+import { isFirstPartyDefaultPlugin } from "../plugins/defaults/main.js";
 import { isPluginDisabled } from "../plugins/disabled-state.js";
 import { getDiscoveredUserPluginNames } from "../plugins/mtime-cache.js";
 import type { HookEntry, HookFunction } from "../plugins/types.js";
@@ -78,35 +81,74 @@ export function unregisterPluginHooks(pluginName: string): void {
 // ─── Queries ─────────────────────────────────────────────────────────────────
 
 /**
- * Get all hooks for a given event name from user plugins and standalone
- * workspace hooks, from the hook loader's in-memory cache. Plugin hooks run
+ * In-process (default plugin) hook entries for `name`, filtered by the
+ * `.disabled` sentinel at read time. First-party default plugins always pass
+ * the per-chat allowlist; other in-process registrations (test fixtures) honor
+ * it. Used by {@link getUserHookEntriesFor} so `getUserHooksFor` returns the
+ * same default-plugin hooks {@link getHooksFor} does.
+ */
+function collectInProcessHookEntries<TCtx = unknown>(
+  name: string,
+  effectiveEnabledPlugins?: Set<string> | null,
+): HookEntry<TCtx>[] {
+  const defaultEntries: HookEntry<TCtx>[] = [];
+  for (const entry of hookRegistry.get(name) ?? []) {
+    if (isPluginDisabled(entry.pluginName)) {
+      continue;
+    }
+    if (
+      effectiveEnabledPlugins != null &&
+      !effectiveEnabledPlugins.has(entry.pluginName) &&
+      !isFirstPartyDefaultPlugin(entry.pluginName)
+    ) {
+      continue;
+    }
+    defaultEntries.push({
+      fn: entry.fn as HookFunction<TCtx>,
+      owner: { kind: "plugin", id: entry.pluginName },
+    });
+  }
+  return defaultEntries;
+}
+
+/**
+ * Get all hooks for a given event name: in-process default-plugin hooks
+ * first, then user plugins and standalone workspace hooks. Plugin hooks run
  * in install-date order, the workspace hook runs last.
  *
- * This is a pure cache read: it never scans disk, activates a plugin, or
- * runs `init`. Activation happens only at boot (`populateCacheAtBoot`)
- * and through the imperative install/uninstall poke
- * (`reconcilePluginSourcesNow`), both main-daemon paths, so a
+ * Default-plugin hooks come from the in-process registry (registration at
+ * boot). User-land hooks are a pure cache read: this never scans disk,
+ * activates a plugin, or runs `init`. Activation happens only at boot
+ * (`populateCacheAtBoot`) and through the imperative install/uninstall
+ * poke (`reconcilePluginSourcesNow`), both main-daemon paths, so a
  * sidecar process that dispatches hooks (a worker running conversation
  * turns) can never bring a plugin up in its own process.
  *
  * `effectiveEnabledPlugins` carries the per-chat plugin scope: when non-null,
- * user plugins outside the set are skipped (standalone workspace hooks always
- * run). `null`/omitted means no per-chat restriction.
+ * user plugins outside the set are skipped. First-party default plugins
+ * always pass that allowlist (a workspace `.disabled` sentinel still
+ * excludes them). Standalone workspace hooks always run. `null`/omitted
+ * means no per-chat restriction.
  */
 export async function getUserHookEntriesFor<TCtx = unknown>(
   hookName: string,
   effectiveEnabledPlugins?: Set<string> | null,
 ): Promise<HookEntry<TCtx>[]> {
-  return collectUserHookEntries<TCtx>(
+  const defaultEntries = collectInProcessHookEntries<TCtx>(
+    hookName,
+    effectiveEnabledPlugins,
+  );
+  const userEntries = await collectUserHookEntries<TCtx>(
     hookName,
     getDiscoveredUserPluginNames(),
     effectiveEnabledPlugins,
   );
+  return [...defaultEntries, ...userEntries];
 }
 
 /**
  * {@link getUserHookEntriesFor} without owner attribution. Returns just the
- * hook functions in the same order.
+ * hook functions in the same order, including in-process default-plugin hooks.
  */
 export async function getUserHooksFor<TCtx = unknown>(
   hookName: string,
@@ -131,17 +173,19 @@ export async function getUserHooksFor<TCtx = unknown>(
  * (async, pure cache read). Default hooks are prepended so they compose
  * innermost, ahead of any user plugins.
  *
- * The `TCtx` generic mirrors {@link HookFunction}'s — callers parameterize
+ * The `TCtx` generic mirrors {@link HookFunction}'s: callers parameterize
  * over the concrete context type their hook receives. Hooks that mutate the
  * context in place return `void`; hooks that return a new context replace
  * the threaded value for the next hook in the chain.
  *
  * When `conversationId` is given, the conversation's effective plugin scope is
  * resolved from it (memory, then DB) and layered on top of the global disabled
- * check: a hook's contributing plugin must also be a member of that set or the
- * hook is excluded for this turn (applies to both in-process default plugins
- * and user-land plugins). Omit it (or pass a conversation with no per-chat
- * restriction) and every globally-enabled plugin's hooks run, unchanged.
+ * check: a user plugin must also be a member of that set or its hook is
+ * excluded for this turn. First-party default plugins are not subject to the
+ * per-chat allowlist (they are core runtime infrastructure; the chat pills
+ * only list user-installed plugins), but a workspace `.disabled` sentinel
+ * still excludes them. Omit `conversationId` (or pass a conversation with no
+ * per-chat restriction) and every globally-enabled plugin's hooks run.
  */
 export async function getHookEntriesFor<TCtx = unknown>(
   name: string,
@@ -160,37 +204,7 @@ export async function getHookEntriesFor<TCtx = unknown>(
       options.conversationId,
     );
   }
-  // First-party defaults from the hook registry, filtered by the `.disabled`
-  // sentinel at read time. This is what makes `assistant plugins disable
-  // default-*` take effect immediately in a running assistant: the hooks stay
-  // registered but are filtered out on the next turn.
-  const defaultEntries: HookEntry<TCtx>[] = [];
-  for (const entry of hookRegistry.get(name) ?? []) {
-    if (isPluginDisabled(entry.pluginName)) {
-      continue;
-    }
-    if (
-      effectiveEnabledPlugins != null &&
-      !effectiveEnabledPlugins.has(entry.pluginName)
-    ) {
-      continue;
-    }
-    defaultEntries.push({
-      fn: entry.fn as HookFunction<TCtx>,
-      owner: { kind: "plugin", id: entry.pluginName },
-    });
-  }
-
-  // User-land hooks from the plugin cache (async, pure cache read; dispatch
-  // never activates plugins). The per-chat
-  // scope is threaded through so a deselected user plugin's hooks are excluded
-  // too — standalone workspace hooks (not owned by a plugin) always run.
-  const userEntries = await getUserHookEntriesFor<TCtx>(
-    name,
-    effectiveEnabledPlugins,
-  );
-
-  return [...defaultEntries, ...userEntries];
+  return getUserHookEntriesFor<TCtx>(name, effectiveEnabledPlugins);
 }
 
 /**

package/src/ipc/__tests__/socket-path.test.ts

@@ -1,10 +1,14 @@
 import { createServer } from "node:net";
 import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
 import { ensureSocketPathFree } from "../socket-cleanup.js";
 import { resolveIpcSocketPath } from "../socket-path.js";
 
+// Fake workspace under tmpdir so the live-workspace guard accepts it.
+const WS_DIR = join(tmpdir(), "vellum-workspace-test");
+
 let savedWorkspaceDir: string | undefined;
 let savedGatewayIpcSocketDir: string | undefined;
 
@@ -29,7 +33,7 @@ afterEach(() => {
 describe("resolveIpcSocketPath", () => {
   test("uses env var override when set", () => {
     process.env.GATEWAY_IPC_SOCKET_DIR = "/run/gateway-ipc";
-    process.env.VELLUM_WORKSPACE_DIR = "/tmp/vellum-workspace-test";
+    process.env.VELLUM_WORKSPACE_DIR = WS_DIR;
 
     const resolved = resolveIpcSocketPath("gateway");
 
@@ -39,28 +43,32 @@ describe("resolveIpcSocketPath", () => {
 
   test("ignores empty env var override", () => {
     process.env.GATEWAY_IPC_SOCKET_DIR = "  ";
-    process.env.VELLUM_WORKSPACE_DIR = "/tmp/vellum-workspace-test";
+    process.env.VELLUM_WORKSPACE_DIR = WS_DIR;
 
     const resolved = resolveIpcSocketPath("gateway");
 
     expect(resolved.source).toBe("workspace");
-    expect(resolved.path).toBe("/tmp/vellum-workspace-test/gateway.sock");
+    expect(resolved.path).toBe(join(WS_DIR, "gateway.sock"));
   });
 
   test("uses workspace path by default", () => {
     delete process.env.GATEWAY_IPC_SOCKET_DIR;
-    process.env.VELLUM_WORKSPACE_DIR = "/tmp/vellum-workspace-test";
+    process.env.VELLUM_WORKSPACE_DIR = WS_DIR;
 
     const resolved = resolveIpcSocketPath("gateway");
 
     expect(resolved.source).toBe("workspace");
-    expect(resolved.path).toBe("/tmp/vellum-workspace-test/gateway.sock");
+    expect(resolved.path).toBe(join(WS_DIR, "gateway.sock"));
   });
 
   test("falls back to tmpdir when workspace path exceeds AF_UNIX limit", () => {
     delete process.env.GATEWAY_IPC_SOCKET_DIR;
     // 90-char workspace dir + /gateway.sock = well over 103 bytes
-    process.env.VELLUM_WORKSPACE_DIR = "/tmp/" + "a".repeat(85) + "/workspace";
+    process.env.VELLUM_WORKSPACE_DIR = join(
+      tmpdir(),
+      "a".repeat(90),
+      "workspace",
+    );
 
     const resolved = resolveIpcSocketPath("gateway");
 
@@ -70,7 +78,7 @@ describe("resolveIpcSocketPath", () => {
 
   test("derives a hyphenated socket name's env var and filename", () => {
     process.env.EXAMPLE_SERVICE_IPC_SOCKET_DIR = "/run/example-ipc";
-    process.env.VELLUM_WORKSPACE_DIR = "/tmp/vellum-workspace-test";
+    process.env.VELLUM_WORKSPACE_DIR = WS_DIR;
 
     const resolved = resolveIpcSocketPath("example-service");
 

package/src/ipc/gateway-client.test.ts

@@ -143,7 +143,7 @@ describe("ipcClassifyRisk retry", () => {
   const CLASSIFY_OK = {
     risk: "low",
     reason: "safe",
-    matchType: "none",
+    matchType: "registry",
     scopeOptions: [],
   };
   const emptyParams = {} as unknown as Parameters<typeof ipcClassifyRisk>[0];

package/src/ipc/gateway-client.ts

@@ -10,16 +10,17 @@
  * deterministic fallback for long AF_UNIX paths.
  */
 
+import {
+  type ClassifyRiskIpcParams,
+  type ClassifyRiskIpcResponse,
+  ClassifyRiskIpcResponseSchema,
+} from "@vellumai/gateway-client";
 import {
   ipcCall as packageIpcCall,
   IpcCallError,
   PersistentIpcClient as PackagePersistentIpcClient,
 } from "@vellumai/gateway-client/ipc-client";
 
-import type {
-  ClassificationResult,
-  ClassifyRiskParams,
-} from "../permissions/ipc-risk-types.js";
 import { getLogger } from "../util/logger.js";
 import { abortableSleep, computeRetryDelay } from "../util/retry.js";
 import { resolveIpcSocketPath } from "./socket-path.js";
@@ -173,37 +174,29 @@ const CLASSIFY_RISK_ATTEMPT_TIMEOUT_MS = 1_500; // per-attempt cap (< 5s default
  * When a `signal` is supplied, retries stop as soon as it aborts.
  */
 export async function ipcClassifyRisk(
-  params: ClassifyRiskParams,
+  params: ClassifyRiskIpcParams,
   signal?: AbortSignal,
-): Promise<ClassificationResult | undefined> {
+): Promise<ClassifyRiskIpcResponse | undefined> {
   for (let attempt = 0; ; attempt++) {
     try {
       const result = await ipcCallPersistent(
         "classify_risk",
-        params as unknown as Record<string, unknown>,
+        params,
         CLASSIFY_RISK_ATTEMPT_TIMEOUT_MS,
       );
 
-      // Returned-but-malformed responses are deterministic, not transient:
+      // A returned-but-malformed response is deterministic, not transient:
       // fail closed immediately (no retry).
-      if (!result || typeof result !== "object" || Array.isArray(result)) {
-        log.warn(
-          { result },
-          "ipcClassifyRisk: gateway returned non-object response",
-        );
-        return undefined;
-      }
-
-      const obj = result as Record<string, unknown>;
-      if (typeof obj.risk !== "string") {
+      const parsed = ClassifyRiskIpcResponseSchema.safeParse(result);
+      if (!parsed.success) {
         log.warn(
-          { result },
-          "ipcClassifyRisk: gateway response missing 'risk' field",
+          { result, issues: parsed.error.issues },
+          "ipcClassifyRisk: gateway response does not match the classify_risk contract",
         );
         return undefined;
       }
 
-      return result as ClassificationResult;
+      return parsed.data;
     } catch (err) {
       // A structured gateway error means the gateway was reachable and
       // deterministically rejected the request — not a transient blip.

package/src/ipc/socket-cleanup.ts

@@ -15,6 +15,8 @@ import {
   removeIpcEndpointFile,
 } from "@vellumai/ipc-server-utils";
 
+import { makeAddrInUseError } from "../daemon/startup-error.js";
+
 /**
  * Maximum time to wait for the probe `connect()` to settle before declaring
  * the path occupied. Without a bound, a hung process holding the socket would
@@ -25,17 +27,6 @@ import {
  */
 const PROBE_CONNECT_TIMEOUT_MS = 2000;
 
-/**
- * Build an `EADDRINUSE`-coded error so callers (and `categorizeDaemonError`)
- * can branch on `err.code` and surface the structured "already running"
- * guidance instead of a generic UNKNOWN.
- */
-function makeAddrInUseError(message: string): NodeJS.ErrnoException {
-  const err = new Error(message) as NodeJS.ErrnoException;
-  err.code = "EADDRINUSE";
-  return err;
-}
-
 /**
  * Probe-connect to `socketPath`. Behavior:
  *   - Path doesn't exist → return.

package/src/mcp/__tests__/mcp-auth-orchestrator.test.ts

@@ -67,7 +67,7 @@ mock.module("../../daemon/mcp-reload-service.js", () => ({
 
 mock.module("../../config/env-registry.js", () => ({
   getIsContainerized: () => false,
-  getWorkspaceDirOverride: () => undefined,
+  getWorkspaceDirOverride: () => process.env.VELLUM_WORKSPACE_DIR,
   // Imported by the real util/logger.js; ESM named-import validation
   // requires it even though the silent test logger never calls it.
   getDebugStdoutLogs: () => false,

package/src/messaging/provider-message-metadata.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+
+import { CHANNEL_IDS } from "../channels/types.js";
+
+/**
+ * What a stored channel message row knows about itself, in terms no single
+ * provider owns.
+ *
+ * "Provider" here is the channel sense, the one `messaging/providers/*` uses:
+ * Slack, Telegram, Discord. It is not the inference sense in `providers/*`,
+ * whose `providerMetadata` rides on a content block and describes a model.
+ *
+ * Named for the provider rather than the channel because `channel metadata`
+ * is already taken: `buildChannelMetadata` builds the whole envelope a
+ * message row carries (provenance, `userMessageChannel`, interfaces), and
+ * this is one key inside that envelope. This is the neutral counterpart of
+ * `slackMeta`, so it reads as the generalization of what `providers/slack`
+ * stores.
+ *
+ * Every channel needs the same facts to reconstruct a transcript: which chat
+ * the row belongs to, the provider's id for the row itself, the thread it sits
+ * in, whether it is a message or a reaction, and, when it is a reaction, which
+ * message it was attached to.
+ *
+ * History assembly is structural, not Slack logic: it groups a reaction with
+ * the message it targets, inside a thread. That rule holds for any
+ * thread-scoped channel.
+ *
+ * The schema passes through what it does not name, so a provider carries its
+ * own fields (Slack's file markers and timezone labels) on this same object
+ * and validates them with its own schema. This is how `SourceMetadataSchema`
+ * already carries `slackBotMentioned` and the email fields on the wire: one
+ * object per row, no per-provider sub-envelope, and no second copy of
+ * anything named here.
+ */
+
+const providerReactionMetadataSchema = z.object({
+  /**
+   * Provider id of the message this reaction was attached to, in the same
+   * namespace as `messageId`. Resolution is keyed on it, so it is required.
+   */
+  targetMessageId: z.string(),
+  emoji: z.string(),
+  op: z.enum(["added", "removed"]),
+  actorDisplayName: z.string().optional(),
+});
+
+export const providerMessageMetadataSchema = z
+  .object({
+    source: z.enum(CHANNEL_IDS),
+    /**
+     * Provider id of the chat, channel or room this row belongs to. Same name
+     * and meaning as on the inbound wire, where "conversation" is the canonical
+     * word for a delivery address and "channel" names the provider.
+     */
+    conversationExternalId: z.string(),
+    /**
+     * Provider id of this row itself. Absent on a reaction, which no channel
+     * gives an id of its own: a reaction event names the chat, the message it
+     * was attached to, the actor and the emoji, and nothing identifies the
+     * reaction. The message it acts on is `reaction.targetMessageId`.
+     */
+    messageId: z.string().optional(),
+    /**
+     * Provider id of the thread this row sits in, absent when it is not in one.
+     * Never synthesized from `messageId`: a value here asserts that a thread
+     * exists, and inventing one keys conversations on threads that never do.
+     */
+    threadId: z.string().optional(),
+    /**
+     * Provider id of whoever authored the row or performed the reaction. Trust
+     * is keyed on this everywhere else, and it is what lets a channel say who
+     * acted; a display name is a label, not an identity. Optional because a
+     * provider envelope need not carry one.
+     */
+    actorExternalId: z.string().optional(),
+    displayName: z.string().optional(),
+    /**
+     * Only reactions get a row of their own. An edit rewrites the row it
+     * targets and a delete stamps `deletedAt` on it, so neither appears here.
+     */
+    eventKind: z.enum(["message", "reaction"]),
+    reaction: providerReactionMetadataSchema.optional(),
+    editedAt: z.number().optional(),
+    deletedAt: z.number().optional(),
+  })
+  .passthrough();
+
+export type ProviderReactionMetadata = z.infer<
+  typeof providerReactionMetadataSchema
+>;
+export type ProviderMessageMetadata = z.infer<
+  typeof providerMessageMetadataSchema
+>;
+
+/**
+ * Parse and validate a serialized `ProviderMessageMetadata`, the counterpart of
+ * `readSlackMetadata` for the neutral shape. Anything that does not parse or
+ * does not validate reads as null.
+ */
+export function readProviderMessageMetadata(
+  raw: unknown,
+): ProviderMessageMetadata | null {
+  if (typeof raw !== "string") {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const result = providerMessageMetadataSchema.safeParse(parsed);
+  return result.success ? result.data : null;
+}
+
+/**
+ * The id a row is grouped by when assembling a thread: its own for a message,
+ * its target's for a reaction, so a reaction lands beside the message it was
+ * attached to rather than in a block of its own.
+ *
+ * Undefined for a row that identifies neither, which cannot be placed.
+ */
+export function groupingMessageId(
+  meta: ProviderMessageMetadata,
+): string | undefined {
+  return meta.reaction?.targetMessageId ?? meta.messageId;
+}