@vellumai/assistant 0.7.1 → 0.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -42,11 +42,12 @@
     "@sentry/node": "10.43.0",
     "@vellumai/ces-client": "file:../packages/ces-client",
     "@vellumai/credential-storage": "file:../packages/credential-storage",
-    "@vellumai/service-contracts": "file:../packages/service-contracts",
     "@vellumai/egress-proxy": "file:../packages/egress-proxy",
     "@vellumai/gateway-client": "file:../packages/gateway-client",
+    "@vellumai/service-contracts": "file:../packages/service-contracts",
     "@vellumai/skill-host-contracts": "file:../packages/skill-host-contracts",
     "@vellumai/slack-text": "file:../packages/slack-text",
+    "@vellumai/twilio-client": "file:../packages/twilio-client",
     "archiver": "7.0.1",
     "commander": "13.1.0",
     "croner": "10.0.1",
@@ -61,6 +62,7 @@
     "playwright": "1.58.2",
     "postgres": "3.4.8",
     "rrule": "2.8.1",
+    "stemmer": "2.0.1",
     "tar-stream": "3.1.7",
     "tldts": "7.0.25",
     "uuid": "11.1.0",
@@ -77,7 +79,8 @@
     "@vellumai/egress-proxy",
     "@vellumai/gateway-client",
     "@vellumai/skill-host-contracts",
-    "@vellumai/slack-text"
+    "@vellumai/slack-text",
+    "@vellumai/twilio-client"
   ],
   "overrides": {
     "lodash": "4.18.1",

package/src/__tests__/app-builder-tool-scripts.test.ts

@@ -93,7 +93,7 @@ describe("app-builder skill tool scripts", () => {
 
     test("delegates to executeAppCreate and returns result", async () => {
       const result = await appCreateScript.run(
-        { name: "My App", html: "<p>Hello</p>" },
+        { name: "My App" },
         makeContext(),
       );
       expect(result.isError).toBe(false);
@@ -107,7 +107,7 @@ describe("app-builder skill tool scripts", () => {
         isError: false,
       });
       const result = await appCreateScript.run(
-        { name: "Auto App", html: "<div/>" },
+        { name: "Auto App" },
         makeContext({ proxyToolResolver: proxy }),
       );
       expect(result.isError).toBe(false);
@@ -118,7 +118,7 @@ describe("app-builder skill tool scripts", () => {
 
     test("handles missing proxyToolResolver gracefully", async () => {
       const result = await appCreateScript.run(
-        { name: "No Proxy", html: "<p/>" },
+        { name: "No Proxy" },
         makeContext(),
       );
       expect(result.isError).toBe(false);

package/src/__tests__/app-bundler.test.ts

@@ -1,4 +1,10 @@
-import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { readFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -22,6 +28,8 @@ const mockApps = new Map<string, Record<string, unknown>>();
 mock.module("../memory/app-store.js", () => ({
   getApp: (id: string) => mockApps.get(id) ?? null,
   getAppsDir: () => testAppsDir,
+  getAppDirPath: (id: string) => join(testAppsDir, id),
+  isMultifileApp: (app: Record<string, unknown>) => app.formatVersion === 2,
 }));
 
 // Mock content-id to avoid pulling in crypto internals
@@ -29,6 +37,52 @@ mock.module("../util/content-id.js", () => ({
   computeContentId: () => "abcd1234abcd1234",
 }));
 
+let compileAppOverride:
+  | ((appDir: string) => Promise<{
+      ok: boolean;
+      errors: Array<{
+        text: string;
+        location?: { file: string; line: number; column: number };
+      }>;
+      warnings: Array<{ text: string }>;
+      durationMs: number;
+    }>)
+  | undefined;
+
+async function compileAppFixture(appDir: string) {
+  if (compileAppOverride) {
+    return compileAppOverride(appDir);
+  }
+
+  const srcDir = join(appDir, "src");
+  const distDir = join(appDir, "dist");
+  rmSync(distDir, { recursive: true, force: true });
+  mkdirSync(distDir, { recursive: true });
+
+  let html = readFileSync(join(srcDir, "index.html"), "utf-8");
+  const cssPath = join(srcDir, "styles.css");
+  if (existsSync(cssPath)) {
+    writeFileSync(join(distDir, "main.css"), readFileSync(cssPath));
+    html = html.replace(
+      "</head>",
+      '  <link rel="stylesheet" href="main.css">\n  </head>',
+    );
+  }
+  html = html.replace(
+    "</body>",
+    '  <script type="module" src="main.js"></script>\n  </body>',
+  );
+
+  writeFileSync(join(distDir, "index.html"), html);
+  writeFileSync(join(distDir, "main.js"), "console.log('compiled');");
+
+  return { ok: true, errors: [], warnings: [], durationMs: 1 };
+}
+
+mock.module("../bundler/app-compiler.js", () => ({
+  compileApp: compileAppFixture,
+}));
+
 // Mock bundle-signer (not exercised in these tests)
 mock.module("./bundle-signer.js", () => ({
   signBundle: async () => ({}),
@@ -43,6 +97,7 @@ import type { AppManifest } from "../bundler/manifest.js";
 
 describe("packageApp", () => {
   afterEach(() => {
+    compileAppOverride = undefined;
     mockApps.clear();
     try {
       rmSync(testAppsDir, { recursive: true, force: true });
@@ -92,6 +147,29 @@ describe("packageApp", () => {
     return appDef;
   }
 
+  function setupLegacyApp(appId: string) {
+    const appDir = join(testAppsDir, appId);
+    mkdirSync(appDir, { recursive: true });
+    writeFileSync(
+      join(appDir, "index.html"),
+      "<!DOCTYPE html><html><body><h1>Legacy</h1></body></html>",
+    );
+
+    const appDef = {
+      id: appId,
+      name: "Legacy App",
+      description: "A legacy app",
+      schemaJson: "{}",
+      htmlDefinition: "<unused>",
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+    writeFileSync(join(testAppsDir, `${appId}.json`), JSON.stringify(appDef));
+    mockApps.set(appId, appDef);
+
+    return appDef;
+  }
+
   test("packages an app with compiled dist/ files in the zip", async () => {
     const appId = "multi-test-1";
     setupApp(appId, { withCss: true });
@@ -140,6 +218,17 @@ describe("packageApp", () => {
     const appDir = join(testAppsDir, appId);
     const srcDir = join(appDir, "src");
     mkdirSync(srcDir, { recursive: true });
+    compileAppOverride = async () => ({
+      ok: false,
+      errors: [
+        {
+          text: "Expected identifier",
+          location: { file: "src/main.tsx", line: 1, column: 20 },
+        },
+      ],
+      warnings: [],
+      durationMs: 1,
+    });
 
     // Write intentionally broken source so esbuild fails
     writeFileSync(join(srcDir, "main.tsx"), "const x: number = {{{BROKEN");
@@ -165,6 +254,70 @@ describe("packageApp", () => {
     );
   });
 
+  test("rejects formatVersion 2 apps missing src files before bundling", async () => {
+    const appId = "multi-missing-src";
+    const appDir = join(testAppsDir, appId);
+    mkdirSync(appDir, { recursive: true });
+    writeFileSync(
+      join(appDir, "index.html"),
+      "<!DOCTYPE html><html><body><h1>Wrong root</h1></body></html>",
+    );
+
+    const appDef = {
+      id: appId,
+      name: "Missing Source App",
+      schemaJson: "{}",
+      htmlDefinition: "<unused>",
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      formatVersion: 2,
+    };
+    writeFileSync(join(testAppsDir, `${appId}.json`), JSON.stringify(appDef));
+    mockApps.set(appId, appDef);
+
+    await expect(packageApp(appId)).rejects.toThrow(
+      /missing src\/index\.html and src\/main\.tsx/,
+    );
+  });
+
+  test("rejects app_create scaffold before sharing", async () => {
+    const appId = "multi-default-scaffold";
+    const appDir = join(testAppsDir, appId);
+    const srcDir = join(appDir, "src");
+    mkdirSync(srcDir, { recursive: true });
+    writeFileSync(
+      join(srcDir, "index.html"),
+      '<!DOCTYPE html><html><body><div id="app"></div></body></html>',
+    );
+    writeFileSync(
+      join(srcDir, "main.tsx"),
+      `import { render } from 'preact';
+
+function App() {
+  return <div>{"Hello, Scaffold!"}</div>;
+}
+
+render(<App />, document.getElementById('app')!);
+`,
+    );
+
+    const appDef = {
+      id: appId,
+      name: "Scaffold App",
+      schemaJson: "{}",
+      htmlDefinition: "<unused>",
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      formatVersion: 2,
+    };
+    writeFileSync(join(testAppsDir, `${appId}.json`), JSON.stringify(appDef));
+    mockApps.set(appId, appDef);
+
+    await expect(packageApp(appId)).rejects.toThrow(
+      /still has the default src\/main\.tsx scaffold/,
+    );
+  });
+
   test("app without CSS omits main.css from zip", async () => {
     const appId = "multi-no-css";
     setupApp(appId, { withCss: false });
@@ -177,4 +330,20 @@ describe("packageApp", () => {
     expect(zip.file("main.js")).not.toBeNull();
     expect(zip.file("main.css")).toBeNull();
   });
+
+  test("keeps legacy single-file apps packageable", async () => {
+    const appId = "legacy-single-file";
+    setupLegacyApp(appId);
+
+    const result = await packageApp(appId);
+    const zipData = await readFile(result.bundlePath);
+    const zip = await JSZip.loadAsync(zipData);
+
+    const indexContent = await zip.file("index.html")!.async("string");
+    const manifestJson = await zip.file("manifest.json")!.async("string");
+    const manifest: AppManifest = JSON.parse(manifestJson);
+
+    expect(indexContent).toContain("<h1>Legacy</h1>");
+    expect(manifest.format_version).toBe(1);
+  });
 });

package/src/__tests__/app-control-flow.test.ts

@@ -0,0 +1,384 @@
+/**
+ * End-to-end app-control flow test.
+ *
+ * Drives a fake conversation through `app_control_start` →
+ * `app_control_observe` → `app_control_stop` using the real
+ * {@link HostAppControlProxy} (so the loop guard, singleton lock, and
+ * result-formatting paths are exercised) plus the real route handler from
+ * `host-app-control-routes.ts`. The mock layer captures broadcast
+ * envelopes and bridges them back through the route handler the way the
+ * desktop client does in production.
+ *
+ * Mirrors `cu-unified-flow.test.ts` for the CU pathway. App-control
+ * differs in two notable ways:
+ *  1. Result payloads carry `pngBase64` (not screenshots-as-strings) and
+ *     surface as image content blocks with `media_type: "image/png"`.
+ *  2. A module-level session lock binds `(conversationId, app)` — only
+ *     one conversation may hold an active session at a time, and non-start
+ *     tools must target the same `app` the user approved at start time.
+ */
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Module mocks (must be installed before importing the units under test)
+// ---------------------------------------------------------------------------
+//
+// Both the proxy (host-proxy-base) and the route handler reach into the
+// `pendingInteractions` and `assistantEventHub` modules. We mock both so
+// the test can:
+//   - capture every broadcast envelope (assertion + driving the route),
+//   - register pending interactions on broadcast (the way production
+//     code does for other host-* requests in `assistant-event-hub.ts`),
+//   - resolve those entries from the route handler.
+//
+// `conversation-store` is intentionally NOT mocked: replacing it would
+// break sibling exports (deleteConversation, etc.) that the
+// `conversation-surfaces.ts` import chain pulls in transitively. We use
+// the real `setConversation` to register fake conversation entries.
+
+const sentMessages: unknown[] = [];
+let mockHasClient = true;
+
+interface PendingEntry {
+  conversationId: string;
+  kind: string;
+}
+const pending = new Map<string, PendingEntry>();
+
+mock.module("../runtime/assistant-event-hub.js", () => ({
+  broadcastMessage: (msg: unknown) => {
+    sentMessages.push(msg);
+    const m = msg as Record<string, unknown>;
+    if (
+      m.type === "host_app_control_request" &&
+      typeof m.requestId === "string" &&
+      typeof m.conversationId === "string"
+    ) {
+      pending.set(m.requestId, {
+        conversationId: m.conversationId,
+        kind: "host_app_control",
+      });
+    }
+  },
+  assistantEventHub: {
+    getMostRecentClientByCapability: (cap: string) =>
+      cap === "host_app_control" && mockHasClient
+        ? { id: "mock-client" }
+        : null,
+  },
+}));
+
+mock.module("../runtime/pending-interactions.js", () => ({
+  register: (requestId: string, entry: PendingEntry) =>
+    pending.set(requestId, entry),
+  get: (requestId: string) => pending.get(requestId),
+  resolve: (requestId: string) => {
+    const entry = pending.get(requestId);
+    if (entry) pending.delete(requestId);
+    return entry;
+  },
+  getByKind: () => [],
+  getByConversation: () => [],
+  removeByConversation: () => {},
+}));
+
+// ---------------------------------------------------------------------------
+// Real imports (after mocks)
+// ---------------------------------------------------------------------------
+
+const {
+  HostAppControlProxy,
+  _getActiveAppControlSession,
+  _resetActiveAppControlSession,
+  _setActiveAppControlSession,
+} = await import("../daemon/host-app-control-proxy.js");
+const { ROUTES } = await import("../runtime/routes/host-app-control-routes.js");
+const { surfaceProxyResolver } =
+  await import("../daemon/conversation-surfaces.js");
+const { setConversation, clearConversations } =
+  await import("../daemon/conversation-store.js");
+type SurfaceConversationContext =
+  import("../daemon/conversation-surfaces.js").SurfaceConversationContext;
+
+const handleHostAppControlResult = ROUTES.find(
+  (r) => r.endpoint === "host-app-control-result",
+)!.handler;
+
+// Tiny base64 PNG-ish placeholder. Content is irrelevant to the result
+// path — the proxy hashes the string for its loop guard but never decodes
+// it, and the resulting content block carries the bytes through verbatim.
+const TINY_PNG_B64 = "iVBORw0KGgoAAAA";
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a SurfaceConversationContext with a real proxy attached. Only the
+ * fields the app-control branch reads are populated — see
+ * `cu-unified-flow.test.ts` for the analogous shape.
+ */
+function buildContext(
+  proxy: InstanceType<typeof HostAppControlProxy>,
+  conversationId = "test-conv",
+): SurfaceConversationContext {
+  return {
+    conversationId,
+    traceEmitter: { emit: () => {} },
+    sendToClient: () => {},
+    pendingSurfaceActions: new Map(),
+    lastSurfaceAction: new Map(),
+    surfaceState: new Map(),
+    surfaceUndoStacks: new Map(),
+    accumulatedSurfaceState: new Map(),
+    surfaceActionRequestIds: new Set(),
+    currentTurnSurfaces: [],
+    hostAppControlProxy: proxy,
+    isProcessing: () => false,
+    enqueueMessage: () => ({ queued: false, requestId: "r1" }),
+    getQueueDepth: () => 0,
+    processMessage: async () => "",
+    withSurface: async (_id, fn) => fn(),
+  };
+}
+
+/**
+ * Register the proxy in the real conversation store keyed by
+ * `conversationId` so the route handler's `findConversation()` lookup
+ * routes POSTed results back to it. The fake conversation only needs the
+ * `hostAppControlProxy` field — the route handler never reads anything
+ * else off it.
+ */
+function registerConversation(
+  conversationId: string,
+  proxy: InstanceType<typeof HostAppControlProxy>,
+): void {
+  setConversation(conversationId, {
+    hostAppControlProxy: proxy,
+  } as never);
+}
+
+/**
+ * Drive the full server → client → server roundtrip: post a result payload
+ * through the real route handler for the most recently broadcast request.
+ */
+async function postResult(body: Record<string, unknown>): Promise<void> {
+  const sent = sentMessages[sentMessages.length - 1] as Record<string, unknown>;
+  const rid = sent.requestId as string;
+  await handleHostAppControlResult({ body: { ...body, requestId: rid } });
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("app-control end-to-end flow", () => {
+  beforeEach(() => {
+    sentMessages.length = 0;
+    pending.clear();
+    clearConversations();
+    mockHasClient = true;
+    _resetActiveAppControlSession();
+  });
+
+  afterEach(() => {
+    _resetActiveAppControlSession();
+    clearConversations();
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 1: app_control_start
+  // -------------------------------------------------------------------------
+
+  test("app_control_start: SSE broadcast → POST result → ToolExecutionResult, lock acquired", async () => {
+    const conversationId = "conv-start";
+    const proxy = new HostAppControlProxy(conversationId);
+    const ctx = buildContext(proxy, conversationId);
+    registerConversation(conversationId, proxy);
+
+    const resultPromise = surfaceProxyResolver(ctx, "app_control_start", {
+      tool: "start",
+      app: "com.example.app",
+    });
+
+    // SSE broadcast captured with the expected envelope shape.
+    expect(sentMessages).toHaveLength(1);
+    const sent = sentMessages[0] as Record<string, unknown>;
+    expect(sent.type).toBe("host_app_control_request");
+    expect(sent.toolName).toBe("app_control_start");
+    expect(sent.conversationId).toBe(conversationId);
+    expect(sent.input).toEqual({ tool: "start", app: "com.example.app" });
+    expect(typeof sent.requestId).toBe("string");
+
+    // The pending interaction is registered (so the route handler can find it).
+    const requestId = sent.requestId as string;
+    expect(pending.has(requestId)).toBe(true);
+
+    // Post a result through the real route handler. The proxy resolves on
+    // the next tick.
+    await postResult({
+      state: "running",
+      pngBase64: TINY_PNG_B64,
+      executionResult: "App launched",
+      windowBounds: { x: 0, y: 0, width: 1280, height: 800 },
+    });
+
+    const result = await resultPromise;
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("State: running");
+    expect(result.content).toContain("App launched");
+    expect(result.content).toContain("1280x800 at (0, 0)");
+    expect(result.contentBlocks).toBeDefined();
+    expect(result.contentBlocks).toHaveLength(1);
+    expect(result.contentBlocks![0]).toEqual({
+      type: "image",
+      source: {
+        type: "base64",
+        media_type: "image/png",
+        data: TINY_PNG_B64,
+      },
+    });
+
+    // Session lock is held by this conversation now, bound to the started app.
+    const session = _getActiveAppControlSession();
+    expect(session?.conversationId).toBe(conversationId);
+    expect(session?.app).toBe("com.example.app");
+
+    proxy.dispose();
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 2: app_control_observe
+  // -------------------------------------------------------------------------
+
+  test("app_control_observe: result payload includes image content block", async () => {
+    const conversationId = "conv-observe";
+    const proxy = new HostAppControlProxy(conversationId);
+    const ctx = buildContext(proxy, conversationId);
+    registerConversation(conversationId, proxy);
+    // Prime a session so observe passes the auth gate. This test exercises
+    // the result-formatting path, not the start flow.
+    _setActiveAppControlSession({
+      conversationId,
+      app: "com.example.app",
+    });
+
+    const resultPromise = surfaceProxyResolver(ctx, "app_control_observe", {
+      tool: "observe",
+      app: "com.example.app",
+    });
+
+    expect(sentMessages).toHaveLength(1);
+    const sent = sentMessages[0] as Record<string, unknown>;
+    expect(sent.toolName).toBe("app_control_observe");
+
+    await postResult({
+      state: "running",
+      pngBase64: TINY_PNG_B64,
+      executionResult: "Window observed",
+    });
+
+    const result = await resultPromise;
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("State: running");
+    expect(result.content).toContain("Window observed");
+    expect(result.contentBlocks).toBeDefined();
+    expect(result.contentBlocks).toHaveLength(1);
+    expect(result.contentBlocks![0]).toEqual({
+      type: "image",
+      source: {
+        type: "base64",
+        media_type: "image/png",
+        data: TINY_PNG_B64,
+      },
+    });
+
+    proxy.dispose();
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 3: app_control_stop short-circuits locally
+  // -------------------------------------------------------------------------
+
+  test("app_control_stop: no SSE broadcast, dispose called, lock released", async () => {
+    const conversationId = "conv-stop";
+    const proxy = new HostAppControlProxy(conversationId);
+    const ctx = buildContext(proxy, conversationId);
+    registerConversation(conversationId, proxy);
+
+    // Acquire the lock first via a real start round-trip — otherwise stop
+    // is a no-op against an unset lock.
+    const startPromise = surfaceProxyResolver(ctx, "app_control_start", {
+      tool: "start",
+      app: "com.example.app",
+    });
+    await postResult({ state: "running", pngBase64: TINY_PNG_B64 });
+    await startPromise;
+    expect(_getActiveAppControlSession()?.conversationId).toBe(conversationId);
+
+    // Wrap dispose to verify it was called by the resolver.
+    let disposeCalls = 0;
+    const realDispose = proxy.dispose.bind(proxy);
+    proxy.dispose = () => {
+      disposeCalls++;
+      realDispose();
+    };
+
+    sentMessages.length = 0;
+
+    const result = await surfaceProxyResolver(ctx, "app_control_stop", {
+      tool: "stop",
+    });
+
+    expect(result.isError).toBe(false);
+    expect(result.content.toLowerCase()).toContain("stopped");
+    // No broadcast on the local short-circuit.
+    expect(sentMessages).toHaveLength(0);
+    expect(disposeCalls).toBe(1);
+    // Lock released.
+    expect(_getActiveAppControlSession()).toBeUndefined();
+  });
+
+  // -------------------------------------------------------------------------
+  // Test 4: singleton lock blocks a second conversation
+  // -------------------------------------------------------------------------
+
+  test("singleton lock: second conversation's start is rejected naming the holder", async () => {
+    const proxyA = new HostAppControlProxy("conv-a");
+    const ctxA = buildContext(proxyA, "conv-a");
+    registerConversation("conv-a", proxyA);
+
+    const startA = surfaceProxyResolver(ctxA, "app_control_start", {
+      tool: "start",
+      app: "com.example.app",
+    });
+    await postResult({ state: "running", pngBase64: TINY_PNG_B64 });
+    const resultA = await startA;
+    expect(resultA.isError).toBe(false);
+    expect(_getActiveAppControlSession()?.conversationId).toBe("conv-a");
+
+    // Second conversation tries to start while conv-a holds the lock.
+    sentMessages.length = 0;
+    const proxyB = new HostAppControlProxy("conv-b");
+    const ctxB = buildContext(proxyB, "conv-b");
+    registerConversation("conv-b", proxyB);
+
+    const resultB = await surfaceProxyResolver(ctxB, "app_control_start", {
+      tool: "start",
+      app: "com.example.app",
+    });
+
+    expect(resultB.isError).toBe(true);
+    expect(resultB.content).toContain("conv-a");
+    expect(resultB.content.toLowerCase()).toContain(
+      "currently holds the app-control session",
+    );
+    // No envelope was dispatched for the rejected start.
+    expect(sentMessages).toHaveLength(0);
+
+    proxyA.dispose();
+    proxyB.dispose();
+  });
+});