@vellumai/assistant 0.10.9-staging.1 → 0.10.9-staging.2

package/AGENTS.md

@@ -73,6 +73,10 @@ Some routes are IPC-only (defined in `src/ipc/routes/`, not in the shared array)
 
 The module-level dependency-injection pattern (`registerFooDeps()`) used by some IPC routes is a known antipattern. New IPC-only routes should avoid it.
 
+## Telemetry wire contract
+
+Telemetry event types are defined by a platform-generated wire contract (`src/telemetry/telemetry-wire.generated.ts`) that `src/telemetry/types.ts` layers over, with pre-flush validation against it. Adding a new event type starts platform-side, not here. The mechanics, the drift guards, and the cross-repo ordering are documented next to the code they govern: see [`src/telemetry/AGENTS.md`](src/telemetry/AGENTS.md).
+
 ## Code comments
 
 When writing or updating comments, **do not reference code that has been removed.** Comments should describe the current state of the codebase, not narrate its history. Avoid phrases like "no longer does X", "previously used Y", or "was removed in PR Z" — future readers should not need to understand past implementations to understand the current code.

package/knip.json

@@ -9,10 +9,7 @@
     "src/config/bundled-skills/**/tools/**/*.ts!"
   ],
   "project": ["src/**/*.ts!", "src/**/*.tsx!", "scripts/**/*.ts"],
-  "ignore": [
-    "src/config/preloaded-apps/**",
-    "src/telemetry/telemetry-wire.generated.ts"
-  ],
+  "ignore": ["src/config/preloaded-apps/**"],
   "ignoreDependencies": [
     "@microsoft/api-extractor",
     "@vellumai/ces-client",

package/openapi.yaml

@@ -3,7 +3,7 @@
 openapi: 3.1.0
 info:
   title: Vellum Assistant API
-  version: 0.10.9
+  version: 0.10.8
   description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server.
 servers:
   - url: http://127.0.0.1:7821
@@ -606,6 +606,8 @@ paths:
                           type: string
                         contentId:
                           type: string
+                        origin:
+                          type: string
                       required:
                         - id
                         - name
@@ -613,6 +615,7 @@ paths:
                         - updatedAt
                         - version
                         - contentId
+                        - origin
                       additionalProperties: false
                 required:
                   - apps
@@ -11554,6 +11557,27 @@ paths:
                   - lines
                   - truncated
                 additionalProperties: false
+  /v1/gateway/status:
+    get:
+      operationId: gateway_status_get
+      summary: Get gateway status
+      description:
+        Reports the gateway's public tunnel status. `tunnel` holds the active public URL when a tunnel is connected
+        and is omitted otherwise. Errors with 503 when the gateway is not running. The tunnel only matters for routing
+        inbound Twilio webhooks and live voice/audio WebSockets.
+      tags:
+        - gateway
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  tunnel:
+                    type: string
+                additionalProperties: false
   /v1/groups:
     get:
       operationId: groups_get
@@ -21925,7 +21949,9 @@ paths:
     get:
       operationId: platform_status_get
       summary: Get platform deployment context and connection status
-      description: Aggregates platform context, credentials, assistant ID, webhook secret, and Velay tunnel status.
+      description:
+        Aggregates platform context, credentials, assistant ID, and webhook secret. Velay tunnel status is reported
+        separately by gateway_status.
       tags:
         - platform
       responses:
@@ -21960,21 +21986,6 @@ paths:
                     anyOf:
                       - type: string
                       - type: "null"
-                  velayTunnel:
-                    anyOf:
-                      - type: object
-                        properties:
-                          connected:
-                            type: boolean
-                          publicUrl:
-                            anyOf:
-                              - type: string
-                              - type: "null"
-                        required:
-                          - connected
-                          - publicUrl
-                        additionalProperties: false
-                      - type: "null"
                 required:
                   - isPlatform
                   - baseUrl
@@ -21985,7 +21996,6 @@ paths:
                   - available
                   - organizationId
                   - userId
-                  - velayTunnel
                 additionalProperties: false
   /v1/playground/seed-conversation:
     post:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.9-staging.1",
+  "version": "0.10.9-staging.2",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/always-loaded-tools-guard.test.ts

@@ -13,10 +13,8 @@
 
 import { afterAll, describe, expect, test } from "bun:test";
 
-import {
-  isToolActiveForContext,
-  type SkillProjectionContext,
-} from "../daemon/conversation-tool-setup.js";
+import type { Conversation } from "../daemon/conversation.js";
+import { isToolActiveForContext } from "../daemon/conversation-tool-setup.js";
 import {
   __resetRegistryForTesting,
   getAllToolDefinitions,
@@ -33,13 +31,13 @@ describe("always-loaded tool count", () => {
     const allDefs = getAllToolDefinitions();
 
     // Minimal context: no client, no capabilities
-    const minimalContext: SkillProjectionContext = {
+    const minimalContext = {
       skillProjectionState: new Map(),
       skillProjectionCache: {},
       toolsDisabledDepth: 0,
       hasNoClient: true,
       channelCapabilities: undefined,
-    };
+    } as unknown as Conversation;
 
     const activeTools = allDefs.filter((def) =>
       isToolActiveForContext(def.name, minimalContext),

package/src/__tests__/app-routes-csp.test.ts

@@ -27,10 +27,19 @@ const apps = new Map<string, typeof legacyApp | typeof multifileApp>([
 ]);
 
 mock.module("../apps/app-store.js", () => ({
-  getApp: (id: string) => apps.get(id) ?? null,
-  getAppsDir: () => "/fake/apps",
-  getAppDirPath: (appId: string) => `/fake/apps/${appId}`,
-  isMultifileApp: (app: Record<string, unknown>) => app.formatVersion === 2,
+  resolveAppSource: (id: string) => {
+    const app = apps.get(id);
+    if (!app) return null;
+    return {
+      id,
+      name: app.name,
+      dirName: id,
+      sourceDir: `/fake/apps/${id}`,
+      origin: { kind: "workspace" as const },
+      formatVersion: (app as { formatVersion?: number }).formatVersion ?? 1,
+    };
+  },
+  readAppFileBytesFromDir: () => Buffer.from(""),
 }));
 
 // Mock shared-app-links-store (imported by app-routes but unused here)

package/src/__tests__/conversation-tool-setup-tools-disabled.test.ts

@@ -28,10 +28,8 @@ mock.module("../daemon/conversation-skill-tools.js", () => ({
 // Import after mocks
 // ---------------------------------------------------------------------------
 
-import {
-  createResolveToolsCallback,
-  type SkillProjectionContext,
-} from "../daemon/conversation-tool-setup.js";
+import type { Conversation } from "../daemon/conversation.js";
+import { createResolveToolsCallback } from "../daemon/conversation-tool-setup.js";
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -41,15 +39,13 @@ function makeToolDef(name: string): ToolDefinition {
   return { name, description: `${name} tool`, input_schema: {} };
 }
 
-function makeCtx(
-  overrides: Partial<SkillProjectionContext> = {},
-): SkillProjectionContext {
+function makeCtx(overrides: Partial<Conversation> = {}): Conversation {
   return {
     skillProjectionState: new Map(),
     skillProjectionCache: {} as SkillProjectionCache,
     toolsDisabledDepth: 0,
     ...overrides,
-  };
+  } as unknown as Conversation;
 }
 
 const EMPTY_HISTORY: Message[] = [];

package/src/__tests__/disk-pressure-tools.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 
+import type { Conversation } from "../daemon/conversation.js";
 import type { SkillProjectionCache } from "../daemon/conversation-skill-tools.js";
-import type { SkillProjectionContext } from "../daemon/conversation-tool-setup.js";
 import type { Message, ToolDefinition } from "../providers/types.js";
 import type { DiskUsageInfo } from "../util/disk-usage.js";
 import * as realDiskUsage from "../util/disk-usage.js";
@@ -74,14 +74,14 @@ function makeToolDef(name: string): ToolDefinition {
 }
 
 function makeProjectionCtx(
-  overrides: Partial<SkillProjectionContext> = {},
-): SkillProjectionContext {
+  overrides: Partial<Conversation> = {},
+): Conversation {
   return {
     skillProjectionState: new Map(),
     skillProjectionCache: {} as SkillProjectionCache,
     toolsDisabledDepth: 0,
     ...overrides,
-  };
+  } as unknown as Conversation;
 }
 
 function setDiskUsage(usedMb: number, totalMb = 100): void {

package/src/__tests__/file-list-tool.test.ts

@@ -9,9 +9,9 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, test } from "bun:test";
 
+import type { Conversation } from "../daemon/conversation.js";
 import {
   isToolActiveForContext,
-  type SkillProjectionContext,
   SUBAGENT_ONLY_TOOL_NAMES,
 } from "../daemon/conversation-tool-setup.js";
 import { fileListTool } from "../tools/filesystem/list.js";
@@ -60,7 +60,9 @@ describe("FileSystemOps.listDirSafe", () => {
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
     const result = ops.listDirSafe({ path: dir });
     expect(result.ok).toBe(true);
-    if (!result.ok) return;
+    if (!result.ok) {
+      return;
+    }
 
     const lines = result.value.listing.split("\n");
     // Directories first with trailing /
@@ -81,7 +83,9 @@ describe("FileSystemOps.listDirSafe", () => {
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
     const result = ops.listDirSafe({ path: dir, glob: "*.md" });
     expect(result.ok).toBe(true);
-    if (!result.ok) return;
+    if (!result.ok) {
+      return;
+    }
 
     const lines = result.value.listing.split("\n");
     expect(lines.length).toBe(2);
@@ -96,7 +100,9 @@ describe("FileSystemOps.listDirSafe", () => {
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
     const result = ops.listDirSafe({ path: join(dir, "regular-file.txt") });
     expect(result.ok).toBe(false);
-    if (result.ok) return;
+    if (result.ok) {
+      return;
+    }
     expect(result.error.code).toBe("NOT_A_DIRECTORY");
   });
 
@@ -106,7 +112,9 @@ describe("FileSystemOps.listDirSafe", () => {
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
     const result = ops.listDirSafe({ path: join(dir, "nonexistent") });
     expect(result.ok).toBe(false);
-    if (result.ok) return;
+    if (result.ok) {
+      return;
+    }
     expect(result.error.code).toBe("NOT_FOUND");
   });
 
@@ -116,7 +124,9 @@ describe("FileSystemOps.listDirSafe", () => {
     const ops = new FileSystemOps(sandboxPolicyFor(dir));
     const result = ops.listDirSafe({ path: "../../../etc" });
     expect(result.ok).toBe(false);
-    if (result.ok) return;
+    if (result.ok) {
+      return;
+    }
     expect(result.error.code).toBe("PATH_OUT_OF_BOUNDS");
   });
 });
@@ -186,31 +196,31 @@ describe("file_list subagent visibility", () => {
   });
 
   test("isToolActiveForContext hides file_list when isSubagent is false", () => {
-    const ctx: SkillProjectionContext = {
+    const ctx = {
       skillProjectionState: new Map(),
       skillProjectionCache: {},
       toolsDisabledDepth: 0,
-    };
+    } as unknown as Conversation;
     expect(isToolActiveForContext("file_list", ctx)).toBe(false);
   });
 
   test("isToolActiveForContext hides file_list when isSubagent is undefined", () => {
-    const ctx: SkillProjectionContext = {
+    const ctx = {
       skillProjectionState: new Map(),
       skillProjectionCache: {},
       toolsDisabledDepth: 0,
       isSubagent: undefined,
-    };
+    } as unknown as Conversation;
     expect(isToolActiveForContext("file_list", ctx)).toBe(false);
   });
 
   test("isToolActiveForContext shows file_list when isSubagent is true", () => {
-    const ctx: SkillProjectionContext = {
+    const ctx = {
       skillProjectionState: new Map(),
       skillProjectionCache: {},
       toolsDisabledDepth: 0,
       isSubagent: true,
-    };
+    } as unknown as Conversation;
     expect(isToolActiveForContext("file_list", ctx)).toBe(true);
   });
 });

package/src/__tests__/list-all-apps.test.ts

@@ -0,0 +1,204 @@
+import { mkdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  createApp,
+  listAllApps,
+  listPluginApps,
+  resolveAppSource,
+} from "../apps/app-store.js";
+import { getWorkspacePluginsDir } from "../util/platform.js";
+
+let workspaceDir: string;
+
+function freshWorkspace(): string {
+  return join(
+    tmpdir(),
+    `vellum-list-all-apps-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+}
+
+/**
+ * Materialize an installed plugin under `<workspace>/plugins/<name>/` with a
+ * package.json manifest. Returns the plugin directory path.
+ */
+function installPlugin(
+  name: string,
+  opts: { disabled?: boolean } = {},
+): string {
+  const pluginDir = join(getWorkspacePluginsDir(), name);
+  mkdirSync(pluginDir, { recursive: true });
+  writeFileSync(
+    join(pluginDir, "package.json"),
+    JSON.stringify({ name, version: "1.0.0" }),
+  );
+  if (opts.disabled) {
+    writeFileSync(join(pluginDir, ".disabled"), "");
+  }
+  return pluginDir;
+}
+
+/**
+ * Bundle an app inside a plugin as a directory under `<pluginDir>/apps/<app>/`.
+ */
+function bundleApp(pluginDir: string, app: string): void {
+  const appDir = join(pluginDir, "apps", app);
+  mkdirSync(appDir, { recursive: true });
+  writeFileSync(join(appDir, "index.html"), "<h1>Plugin app</h1>");
+}
+
+beforeEach(() => {
+  workspaceDir = freshWorkspace();
+  process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
+});
+
+afterEach(() => {
+  rmSync(workspaceDir, { recursive: true, force: true });
+});
+
+describe("listAllApps", () => {
+  test("returns nothing when no apps exist", () => {
+    expect(listAllApps()).toEqual([]);
+    expect(listPluginApps()).toEqual([]);
+  });
+
+  test("tags workspace apps with the workspace origin", () => {
+    const created = createApp({
+      name: "Budget",
+      schemaJson: "{}",
+      htmlDefinition: "<h1>Budget</h1>",
+    });
+
+    const all = listAllApps();
+    expect(all).toHaveLength(1);
+    expect(all[0].origin).toEqual({ kind: "workspace" });
+    expect(all[0].id).toBe(created.id);
+    expect(all[0].name).toBe("Budget");
+    // Workspace source resolves through the dirName-based resolver.
+    expect(all[0].sourcePath).toContain(join("data", "apps"));
+    expect(all[0].sourcePath).toContain(created.dirName ?? created.id);
+  });
+
+  test("discovers plugin apps by directory, tagged plugin:<name>", () => {
+    createApp({
+      name: "Budget",
+      schemaJson: "{}",
+      htmlDefinition: "<h1>Budget</h1>",
+    });
+    const pluginDir = installPlugin("acme");
+    bundleApp(pluginDir, "acme-dashboard");
+
+    const plugin = listPluginApps();
+    expect(plugin).toHaveLength(1);
+    expect(plugin[0].origin).toEqual({ kind: "plugin", pluginName: "acme" });
+    expect(plugin[0].id).toBe("plugins~acme~acme-dashboard");
+    expect(plugin[0].name).toBe("acme-dashboard");
+    expect(plugin[0].sourcePath).toBe(
+      join(pluginDir, "apps", "acme-dashboard"),
+    );
+
+    // Workspace apps come first, then plugin apps.
+    const all = listAllApps();
+    expect(all.map((a) => a.origin.kind)).toEqual(["workspace", "plugin"]);
+  });
+
+  test("ignores directories under plugins/ without a package.json manifest", () => {
+    // A stray directory that is not an installed plugin, even with an apps/ dir.
+    const strayDir = join(getWorkspacePluginsDir(), "not-a-plugin");
+    mkdirSync(join(strayDir, "apps", "ghost"), { recursive: true });
+
+    expect(listPluginApps()).toEqual([]);
+  });
+
+  test("includes apps from a symlinked plugin directory", () => {
+    // Real plugin lives outside plugins/; plugins/<name> is a symlink to it.
+    const realPluginDir = join(workspaceDir, "external-acme");
+    mkdirSync(realPluginDir, { recursive: true });
+    writeFileSync(
+      join(realPluginDir, "package.json"),
+      JSON.stringify({ name: "acme", version: "1.0.0" }),
+    );
+    bundleApp(realPluginDir, "acme-dashboard");
+
+    mkdirSync(getWorkspacePluginsDir(), { recursive: true });
+    symlinkSync(realPluginDir, join(getWorkspacePluginsDir(), "acme"));
+
+    const plugin = listPluginApps();
+    expect(plugin).toHaveLength(1);
+    expect(plugin[0].name).toBe("acme-dashboard");
+    expect(plugin[0].origin).toEqual({ kind: "plugin", pluginName: "acme" });
+  });
+
+  test("excludes apps from disabled plugins", () => {
+    const pluginDir = installPlugin("acme", { disabled: true });
+    bundleApp(pluginDir, "acme-dashboard");
+
+    expect(listPluginApps()).toEqual([]);
+    expect(listAllApps()).toEqual([]);
+  });
+});
+
+describe("resolveAppSource", () => {
+  test("resolves a workspace app by its UUID", () => {
+    const created = createApp({
+      name: "Budget",
+      schemaJson: "{}",
+      htmlDefinition: "<h1>Budget</h1>",
+    });
+
+    const source = resolveAppSource(created.id);
+    expect(source).not.toBeNull();
+    expect(source!.origin).toEqual({ kind: "workspace" });
+    expect(source!.name).toBe("Budget");
+    expect(source!.sourceDir).toContain(join("data", "apps"));
+    // Single-file app (index.html at root).
+    expect(source!.formatVersion).toBe(1);
+  });
+
+  test("resolves a plugin app by its plugins~<name>~<app> id", () => {
+    const pluginDir = installPlugin("acme");
+    bundleApp(pluginDir, "acme-dashboard");
+
+    const source = resolveAppSource("plugins~acme~acme-dashboard");
+    expect(source).not.toBeNull();
+    expect(source!.origin).toEqual({ kind: "plugin", pluginName: "acme" });
+    expect(source!.name).toBe("acme-dashboard");
+    expect(source!.sourceDir).toBe(join(pluginDir, "apps", "acme-dashboard"));
+    // bundleApp writes index.html at the root → single-file.
+    expect(source!.formatVersion).toBe(1);
+  });
+
+  test("returns null for an unknown workspace id", () => {
+    expect(resolveAppSource("11111111-1111-1111-1111-111111111111")).toBeNull();
+  });
+
+  test("returns null for a plugin app whose plugin is disabled", () => {
+    const pluginDir = installPlugin("acme", { disabled: true });
+    bundleApp(pluginDir, "acme-dashboard");
+
+    expect(resolveAppSource("plugins~acme~acme-dashboard")).toBeNull();
+  });
+
+  test("returns null for a plugin dir without a package.json manifest", () => {
+    // Stray directory shaped like a plugin app but not an installed plugin.
+    const strayApp = join(
+      getWorkspacePluginsDir(),
+      "not-a-plugin",
+      "apps",
+      "x",
+    );
+    mkdirSync(strayApp, { recursive: true });
+
+    expect(resolveAppSource("plugins~not-a-plugin~x")).toBeNull();
+  });
+
+  test("returns null for traversal and malformed plugin ids", () => {
+    installPlugin("acme");
+    expect(resolveAppSource("plugins~..~secrets")).toBeNull(); // traversal name
+    expect(resolveAppSource("plugins~acme~..")).toBeNull(); // traversal app
+    expect(resolveAppSource("plugins~acme")).toBeNull(); // missing app segment
+    expect(resolveAppSource("plugins~acme~sub/dir")).toBeNull(); // slash in app
+  });
+});

package/src/__tests__/messaging-send-tool.test.ts

@@ -1,3 +1,6 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 import type { MessagingProvider } from "../messaging/provider.js";
@@ -129,6 +132,7 @@ describe("messaging-send tool", () => {
         subject: undefined,
         inReplyTo: undefined,
         threadId: undefined,
+        attachments: undefined,
         assistantId: "ast-alpha",
       },
     );
@@ -159,11 +163,74 @@ describe("messaging-send tool", () => {
         subject: undefined,
         inReplyTo: undefined,
         threadId: "thread-abc",
+        attachments: undefined,
         assistantId: "ast-alpha",
       },
     );
   });
 
+  test("rejects attachments on platforms that can't carry them", async () => {
+    const result = await run(
+      {
+        platform: "phone",
+        conversation_id: "+12025550142",
+        text: "with a file",
+        attachment_paths: ["/tmp/does-not-matter.pdf"],
+      },
+      {
+        workingDir: "/tmp",
+        conversationId: "conv-1",
+        assistantId: "ast-alpha",
+        trustClass: "guardian" as const,
+      },
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("Gmail and Outlook");
+    expect(sendMessageMock).not.toHaveBeenCalled();
+  });
+
+  test("reads and forwards attachments to attachment-capable non-Gmail providers", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "msg-send-att-"));
+    const filePath = join(dir, "report.pdf");
+    writeFileSync(filePath, "pdf-bytes");
+    provider.id = "outlook";
+
+    try {
+      const result = await run(
+        {
+          platform: "outlook",
+          conversation_id: "user@example.com",
+          text: "see attached",
+          subject: "Docs",
+          attachment_paths: [filePath],
+        },
+        {
+          workingDir: "/tmp",
+          conversationId: "conv-1",
+          assistantId: "ast-alpha",
+          trustClass: "guardian" as const,
+        },
+      );
+
+      expect(result.isError).toBe(false);
+      const options = sendMessageMock.mock.calls[0][3] as {
+        attachments?: Array<{
+          filename: string;
+          mimeType: string;
+          data: Buffer;
+        }>;
+      };
+      expect(options.attachments).toHaveLength(1);
+      expect(options.attachments?.[0]?.filename).toBe("report.pdf");
+      expect(options.attachments?.[0]?.mimeType).toBe("application/pdf");
+      expect(options.attachments?.[0]?.data.toString()).toBe("pdf-bytes");
+    } finally {
+      provider.id = "phone";
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
   test("cross-posts outbound message to bound conversation", async () => {
     getBindingByChannelChatMock.mockImplementation(() => ({
       conversationId: "bound-conv-99",