@vellumai/assistant 0.9.0-staging.1 → 0.9.0

package/node_modules/@vellumai/gateway-client/src/inbound-contract.ts

@@ -0,0 +1,105 @@
+/**
+ * Gateway → daemon inbound payload contract.
+ *
+ * Zod schema defining the wire format for messages forwarded from the
+ * gateway to the daemon via `POST /v1/channels/inbound`. Both services
+ * import from here so the contract is enforced at compile time.
+ *
+ * The gateway constructs this payload in `forwardToRuntime()` from the
+ * normalized `GatewayInboundEvent`; the daemon validates and consumes
+ * it in `handleChannelInbound()`.
+ */
+
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Command intent (channel-initiated commands, e.g. Telegram /start)
+// ---------------------------------------------------------------------------
+
+export const CommandIntentSchema = z.object({
+  type: z.string(),
+  payload: z.string().optional(),
+});
+
+export type CommandIntent = z.infer<typeof CommandIntentSchema>;
+
+// ---------------------------------------------------------------------------
+// Source metadata — structured fields forwarded from the gateway's
+// normalized inbound event. Replaces the untyped Record<string, unknown>.
+// ---------------------------------------------------------------------------
+
+export const SourceMetadataSchema = z
+  .object({
+    /** Provider-assigned update/event ID. */
+    updateId: z.string().optional(),
+    /** Provider message ID (e.g. Slack message `ts`). */
+    messageId: z.string().optional(),
+    /** Provider chat type (e.g. Telegram "private", "group"). */
+    chatType: z.string().optional(),
+    /** Thread/conversation-group ID (e.g. Slack `thread_ts`). */
+    threadId: z.string().optional(),
+    /** Channel name (e.g. Slack channel display name). */
+    channelName: z.string().optional(),
+    /** Actor's language code (e.g. "en", "es"). */
+    languageCode: z.string().optional(),
+    /** Whether the actor is a bot. */
+    isBot: z.boolean().optional(),
+    /** Actor's IANA timezone (e.g. "America/Los_Angeles"). */
+    timezone: z.string().optional(),
+    /** Human-readable timezone label (e.g. "Pacific Daylight Time"). */
+    timezoneLabel: z.string().optional(),
+    /** UTC offset in seconds. */
+    timezoneOffsetSeconds: z.number().optional(),
+    /** Slack-specific: actor is from an external workspace (Slack Connect). */
+    isStranger: z.boolean().optional(),
+    /** Slack-specific: actor is a guest / restricted account. */
+    isRestricted: z.boolean().optional(),
+    /** Transport-layer hints forwarded from the channel adapter. */
+    hints: z.array(z.string()).optional(),
+    /** Transport-layer UX brief. */
+    uxBrief: z.string().optional(),
+    /** Client-provided timezone for date formatting. */
+    clientTimezone: z.string().optional(),
+    /** Channel command intent (e.g. Telegram /start). */
+    commandIntent: CommandIntentSchema.optional(),
+    /** Slack-specific: whether the bot was @-mentioned. */
+    slackBotMentioned: z.boolean().optional(),
+    /** Slack workspace/team ID. */
+    account: z.string().optional(),
+
+    // Email-specific fields
+    /** Email subject line. */
+    emailSubject: z.string().optional(),
+    /** Email recipient address. */
+    emailRecipient: z.string().optional(),
+    /** Email In-Reply-To header. */
+    emailInReplyTo: z.string().optional(),
+    /** Email References header. */
+    emailReferences: z.string().optional(),
+  })
+  .passthrough();
+
+export type SourceMetadata = z.infer<typeof SourceMetadataSchema>;
+
+// ---------------------------------------------------------------------------
+// Runtime inbound payload — the full wire format
+// ---------------------------------------------------------------------------
+
+export const RuntimeInboundPayloadSchema = z.object({
+  sourceChannel: z.string(),
+  interface: z.string(),
+  conversationExternalId: z.string(),
+  externalMessageId: z.string(),
+  content: z.string(),
+  isEdit: z.boolean().optional(),
+  callbackQueryId: z.string().optional(),
+  callbackData: z.string().optional(),
+  actorDisplayName: z.string().optional(),
+  actorExternalId: z.string(),
+  actorUsername: z.string().optional(),
+  sourceMetadata: SourceMetadataSchema.optional(),
+  attachmentIds: z.array(z.string()).optional(),
+  replyCallbackUrl: z.string().optional(),
+});
+
+export type RuntimeInboundPayload = z.infer<typeof RuntimeInboundPayloadSchema>;

package/node_modules/@vellumai/gateway-client/src/index.ts

@@ -32,3 +32,15 @@ export type {
 } from "./types.js";
 
 export { noopLogger } from "./types.js";
+
+export {
+  CommandIntentSchema,
+  RuntimeInboundPayloadSchema,
+  SourceMetadataSchema,
+} from "./inbound-contract.js";
+
+export type {
+  CommandIntent,
+  RuntimeInboundPayload,
+  SourceMetadata,
+} from "./inbound-contract.js";

package/openapi.yaml

@@ -3874,6 +3874,105 @@ paths:
       description: Receive an inbound message from a channel integration.
       tags:
         - channels
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                sourceChannel:
+                  type: string
+                interface:
+                  type: string
+                conversationExternalId:
+                  type: string
+                externalMessageId:
+                  type: string
+                content:
+                  type: string
+                isEdit:
+                  type: boolean
+                callbackQueryId:
+                  type: string
+                callbackData:
+                  type: string
+                actorDisplayName:
+                  type: string
+                actorExternalId:
+                  type: string
+                actorUsername:
+                  type: string
+                sourceMetadata:
+                  type: object
+                  properties:
+                    updateId:
+                      type: string
+                    messageId:
+                      type: string
+                    chatType:
+                      type: string
+                    threadId:
+                      type: string
+                    channelName:
+                      type: string
+                    languageCode:
+                      type: string
+                    isBot:
+                      type: boolean
+                    timezone:
+                      type: string
+                    timezoneLabel:
+                      type: string
+                    timezoneOffsetSeconds:
+                      type: number
+                    isStranger:
+                      type: boolean
+                    isRestricted:
+                      type: boolean
+                    hints:
+                      type: array
+                      items:
+                        type: string
+                    uxBrief:
+                      type: string
+                    clientTimezone:
+                      type: string
+                    commandIntent:
+                      type: object
+                      properties:
+                        type:
+                          type: string
+                        payload:
+                          type: string
+                      required:
+                        - type
+                    slackBotMentioned:
+                      type: boolean
+                    account:
+                      type: string
+                    emailSubject:
+                      type: string
+                    emailRecipient:
+                      type: string
+                    emailInReplyTo:
+                      type: string
+                    emailReferences:
+                      type: string
+                  additionalProperties: {}
+                attachmentIds:
+                  type: array
+                  items:
+                    type: string
+                replyCallbackUrl:
+                  type: string
+              required:
+                - sourceChannel
+                - interface
+                - conversationExternalId
+                - externalMessageId
+                - content
+                - actorExternalId
       responses:
         "200":
           description: Successful response

package/package.json

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

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

@@ -450,6 +450,12 @@ describe("package-resolver", () => {
     expect(ALLOWED_PACKAGES).toContain("lodash-es");
     expect(ALLOWED_PACKAGES).toContain("zod");
     expect(ALLOWED_PACKAGES).toContain("clsx");
-    expect(ALLOWED_PACKAGES).toContain("lucide");
+  });
+
+  // `lucide` (the vanilla package) unpacks to ~29 MB, far above the resolver's
+  // size cap, so it is installed then deleted and never resolves. It also
+  // exports icon data arrays, not Preact components. Apps use inline SVG.
+  test("ALLOWED_PACKAGES excludes lucide", () => {
+    expect(ALLOWED_PACKAGES).not.toContain("lucide");
   });
 });

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

@@ -168,6 +168,49 @@ describe("executeAppCreate", () => {
     expect(parsed.next_steps).toContain("app_refresh");
   });
 
+  test("associates the new app with its conversation when a conversationId is given", async () => {
+    const app = makeMultifileApp({ id: "app-xyz", name: "Assoc App" });
+    const associated: Array<{ appId: string; conversationId: string }> = [];
+    const store: AppStore = {
+      ...mockStore(app, {}),
+      addAppConversationId: (appId, conversationId) => {
+        associated.push({ appId, conversationId });
+        return true;
+      },
+    };
+
+    const result = await executeAppCreate(
+      { name: "Assoc App" },
+      store,
+      undefined,
+      "conv-assoc-1",
+    );
+
+    expect(result.isError).toBe(false);
+    expect(associated).toEqual([
+      { appId: "app-xyz", conversationId: "conv-assoc-1" },
+    ]);
+  });
+
+  test("a failed conversation association does not fail the create", async () => {
+    const app = makeMultifileApp({ id: "app-throw", name: "Throw App" });
+    const store: AppStore = {
+      ...mockStore(app, {}),
+      addAppConversationId: () => {
+        throw new Error("disk gone");
+      },
+    };
+
+    const result = await executeAppCreate(
+      { name: "Throw App" },
+      store,
+      undefined,
+      "conv-assoc-2",
+    );
+
+    expect(result.isError).toBe(false);
+  });
+
   test("skips auto_open on scaffold even when proxy resolver is available", async () => {
     const files: Record<string, string> = {};
     const app = makeMultifileApp({ name: "New App" });

package/src/__tests__/conversation-surfaces-data-persist.test.ts

@@ -416,6 +416,103 @@ describe("ui_surface_update persistence", () => {
   });
 });
 
+describe("ui_dismiss persisted-state convergence", () => {
+  let writes: Array<{ id: string; content: unknown }> = [];
+
+  beforeEach(() => {
+    writes = [];
+    updateMessageContentSpy = (id: string, content: string) => {
+      writes.push({ id, content: JSON.parse(content) });
+    };
+    getMessagesImpl = () => [];
+    cancelPendingSurfaceDataPersists();
+  });
+
+  afterEach(() => {
+    cancelPendingSurfaceDataPersists();
+  });
+
+  test("passive dismiss drops the surface from the turn snapshot and strips the persisted block", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+    const surfaceId = "surface-dismiss-1";
+    // A progress card the model marked `completed` while leaving step 4 spinning.
+    const data: CardSurfaceData = {
+      title: "Refreshing dashboard",
+      body: "",
+      template: "task_progress",
+      templateData: {
+        status: "completed",
+        steps: [{ label: "Surface today's numbers", status: "in_progress" }],
+      },
+    };
+    ctx.surfaceState.set(surfaceId, { surfaceType: "card", data });
+    ctx.currentTurnSurfaces.push({ surfaceId, surfaceType: "card", data });
+    seedRows([
+      {
+        id: "msg-dismiss",
+        content: [
+          { type: "text", text: "done" },
+          { type: "ui_surface", surfaceId, surfaceType: "card", data },
+        ],
+      },
+    ]);
+
+    const result = await surfaceProxyResolver(ctx, "ui_dismiss", {
+      surface_id: surfaceId,
+    });
+    expect(result.isError).toBe(false);
+    expect(result.content).toBe("Surface dismissed");
+
+    // Removed from the pending turn snapshot so turn completion never re-appends it.
+    expect(
+      ctx.currentTurnSurfaces.find((s) => s.surfaceId === surfaceId),
+    ).toBeUndefined();
+
+    // The already-persisted block is stripped; the sibling text block survives.
+    expect(writes).toHaveLength(1);
+    const blocks = writes[0].content as Array<Record<string, unknown>>;
+    expect(blocks.find((b) => b.type === "ui_surface")).toBeUndefined();
+    expect(blocks.find((b) => b.type === "text")).toBeDefined();
+
+    // A passive dismiss event (not a completion) was emitted to the client.
+    expect(sent.some((m) => m.type === "ui_surface_dismiss")).toBe(true);
+    expect(sent.some((m) => m.type === "ui_surface_complete")).toBe(false);
+  });
+
+  test("dismiss cancels a pending debounced persist so a stale update cannot re-add the block", async () => {
+    const sent: ServerMessage[] = [];
+    const ctx = makeContext(sent);
+    const surfaceId = "surface-dismiss-2";
+    const data: CardSurfaceData = {
+      title: "x",
+      body: "",
+      template: "task_progress",
+      templateData: { status: "in_progress" },
+    };
+    ctx.surfaceState.set(surfaceId, { surfaceType: "card", data });
+    seedRows([
+      {
+        id: "msg-dismiss-2",
+        content: [{ type: "ui_surface", surfaceId, surfaceType: "card", data }],
+      },
+    ]);
+
+    // A final ui_update is still inside the debounce window when dismiss fires.
+    scheduleSurfaceDataPersist("conv-persist-1", surfaceId, {
+      ...data,
+      templateData: { status: "completed" },
+    } as SurfaceData);
+
+    await surfaceProxyResolver(ctx, "ui_dismiss", { surface_id: surfaceId });
+    const writeCountAfterDismiss = writes.length;
+
+    // The cancelled debounce must not fire a write that resurrects the block.
+    await new Promise((r) => setTimeout(r, 600));
+    expect(writes).toHaveLength(writeCountAfterDismiss);
+  });
+});
+
 describe("standalone surface DB persistence", () => {
   let writes: Array<{ id: string; content: unknown }> = [];
 

package/src/__tests__/dynamic-page-surface.test.ts

@@ -206,6 +206,100 @@ describe("ui_show dynamic_page app substitute guard", () => {
   });
 });
 
+describe("ui_show empty card guard", () => {
+  function makeCtx(onProxy: () => void) {
+    return {
+      conversationId: "conversation-123",
+      workingDir: "/tmp",
+      trustClass: "guardian" as const,
+      proxyToolResolver: async () => {
+        onProxy();
+        return { content: "proxied", isError: false };
+      },
+    };
+  }
+
+  test("rejects a card carrying only a title and does not proxy", async () => {
+    let proxied = false;
+    const result = await uiShowTool.execute(
+      {
+        surface_type: "card",
+        title: "Vellum Internal Usage app",
+        activity: "Showing progress",
+        data: {},
+      },
+      makeCtx(() => {
+        proxied = true;
+      }),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("card requires content");
+    expect(proxied).toBe(false);
+  });
+
+  test("rejects a card with no content at all", async () => {
+    let proxied = false;
+    const result = await uiShowTool.execute(
+      { surface_type: "card", data: {} },
+      makeCtx(() => {
+        proxied = true;
+      }),
+    );
+
+    expect(result.isError).toBe(true);
+    expect(proxied).toBe(false);
+  });
+
+  test("allows a card with a body", async () => {
+    let proxied = false;
+    const result = await uiShowTool.execute(
+      { surface_type: "card", data: { title: "Plain", body: "hi" } },
+      makeCtx(() => {
+        proxied = true;
+      }),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(proxied).toBe(true);
+  });
+
+  test("allows a task_progress card with empty data (template renders a shell)", async () => {
+    let proxied = false;
+    const result = await uiShowTool.execute(
+      {
+        surface_type: "card",
+        template: "task_progress",
+        templateData: { status: "in_progress", steps: [] },
+      },
+      makeCtx(() => {
+        proxied = true;
+      }),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(proxied).toBe(true);
+  });
+
+  test("allows an action-only card", async () => {
+    let proxied = false;
+    const result = await uiShowTool.execute(
+      {
+        surface_type: "card",
+        title: "Confirm",
+        actions: [{ id: "ok", label: "OK" }],
+        data: {},
+      },
+      makeCtx(() => {
+        proxied = true;
+      }),
+    );
+
+    expect(result.isError).toBe(false);
+    expect(proxied).toBe(true);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // task_progress ui_show appends the update hint to its return value
 // ---------------------------------------------------------------------------

package/src/__tests__/mock-gateway-ipc.ts

@@ -82,6 +82,28 @@ const GET_FEATURE_FLAGS_DEFAULT: Record<string, boolean> = {
   __test_default__: false,
 };
 
+class FakeIpcCallError extends Error {
+  readonly statusCode?: number;
+  readonly errorCode?: string;
+  readonly errorDetails?: unknown;
+
+  constructor(
+    message: string,
+    fields: {
+      statusCode?: number;
+      errorCode?: string;
+      errorDetails?: unknown;
+    } = {},
+  ) {
+    super(message);
+    this.name = "IpcCallError";
+    if (fields.statusCode !== undefined) this.statusCode = fields.statusCode;
+    if (fields.errorCode !== undefined) this.errorCode = fields.errorCode;
+    if (fields.errorDetails !== undefined)
+      this.errorDetails = fields.errorDetails;
+  }
+}
+
 export function installGatewayIpcMock(): void {
   mock.module("@vellumai/gateway-client/ipc-client", () => ({
     ipcCall: async (
@@ -97,6 +119,7 @@ export function installGatewayIpcMock(): void {
       if (method === "get_feature_flags") return GET_FEATURE_FLAGS_DEFAULT;
       return undefined;
     },
+    IpcCallError: FakeIpcCallError,
     PersistentIpcClient: FakePersistentIpcClient,
   }));
 }

package/src/__tests__/resolve-app-id.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, mock, test } from "bun:test";
+
+import type { AppDefinition } from "../memory/app-store.js";
+
+let appsByConversation: AppDefinition[] = [];
+
+const realStore = await import("../memory/app-store.js");
+mock.module("../memory/app-store.js", () => ({
+  ...realStore,
+  listAppsByConversation: (_conversationId: string) => appsByConversation,
+}));
+
+const { resolveAppId, missingAppIdError } =
+  await import("../tools/apps/resolve-app-id.js");
+
+function makeApp(id: string, updatedAt: number): AppDefinition {
+  return {
+    id,
+    name: id,
+    schemaJson: "{}",
+    htmlDefinition: "",
+    createdAt: updatedAt,
+    updatedAt,
+  };
+}
+
+describe("resolveAppId", () => {
+  test("returns an explicit non-empty app_id unchanged", () => {
+    appsByConversation = [makeApp("other", 1)];
+    expect(resolveAppId({ app_id: "explicit" }, "conv-1")).toBe("explicit");
+  });
+
+  test("falls back to the most-recently-updated conversation app when missing", () => {
+    // listAppsByConversation inherits listApps' updatedAt-descending order.
+    appsByConversation = [makeApp("newest", 30), makeApp("older", 10)];
+    expect(resolveAppId({}, "conv-1")).toBe("newest");
+  });
+
+  test("treats a blank app_id as missing", () => {
+    appsByConversation = [makeApp("active", 5)];
+    expect(resolveAppId({ app_id: "   " }, "conv-1")).toBe("active");
+  });
+
+  test("returns null when no app_id is given and the conversation has no app", () => {
+    appsByConversation = [];
+    expect(resolveAppId({}, "conv-1")).toBeNull();
+  });
+});
+
+describe("missingAppIdError", () => {
+  test("is an actionable error result", () => {
+    const result = missingAppIdError();
+    expect(result.isError).toBe(true);
+    expect(JSON.parse(result.content).error).toContain("app_create");
+  });
+});

package/src/bundler/package-resolver.ts

@@ -22,7 +22,6 @@ export const ALLOWED_PACKAGES: readonly string[] = [
   "lodash-es",
   "zod",
   "clsx",
-  "lucide",
 ] as const;
 
 const INSTALL_TIMEOUT_MS = 10_000;

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -196,7 +196,7 @@ render(<App />, document.getElementById("app")!);
 2. **`file_write`** each real file, one per tool call, overwriting the placeholders and adding components.
 3. **`app_refresh`** ONCE at the end to compile.
 
-**Allowed packages** (esbuild-resolved, no CDN): `date-fns`, `chart.js`, `lodash-es`, `zod`, `clsx`, `lucide` (use `lucide`, NOT `lucide-react`).
+**Allowed packages** (esbuild-resolved, no CDN): `date-fns`, `chart.js`, `lodash-es`, `zod`, `clsx`. For icons, write inline `<svg>` markup directly — no icon package is bundled.
 
 **Constraints:** Preact not React. No CDN imports. No external fonts/images (system fonts, inline CSS/SVG). Responsive only, no fixed-pixel widths. The WebView blocks navigation — `href` and form `action` don't work.
 

package/src/config/bundled-skills/app-builder/tools/app-create.ts

@@ -15,5 +15,10 @@ export async function run(
     setAppCommitMessage(context.conversationId, input.change_summary.trim());
   }
   const createInput: AppCreateInput = input as unknown as AppCreateInput;
-  return executeAppCreate(createInput, appStore, context.proxyToolResolver);
+  return executeAppCreate(
+    createInput,
+    appStore,
+    context.proxyToolResolver,
+    context.conversationId,
+  );
 }

package/src/config/bundled-skills/app-builder/tools/app-generate-icon.ts

@@ -2,6 +2,10 @@ import { setAppCommitMessage } from "../../../../memory/app-git-service.js";
 import * as appStore from "../../../../memory/app-store.js";
 import type { AppGenerateIconInput } from "../../../../tools/apps/executors.js";
 import { executeAppGenerateIcon } from "../../../../tools/apps/executors.js";
+import {
+  missingAppIdError,
+  resolveAppId,
+} from "../../../../tools/apps/resolve-app-id.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -14,8 +18,10 @@ export async function run(
   if (typeof input.change_summary === "string" && input.change_summary.trim()) {
     setAppCommitMessage(context.conversationId, input.change_summary.trim());
   }
+  const appId = resolveAppId(input, context.conversationId);
+  if (!appId) return missingAppIdError();
   return executeAppGenerateIcon(
-    input as unknown as AppGenerateIconInput,
+    { ...input, app_id: appId } as unknown as AppGenerateIconInput,
     appStore,
   );
 }

package/src/config/bundled-skills/app-builder/tools/app-refresh.ts

@@ -1,6 +1,10 @@
 import { setAppCommitMessage } from "../../../../memory/app-git-service.js";
 import * as appStore from "../../../../memory/app-store.js";
 import { executeAppRefresh } from "../../../../tools/apps/executors.js";
+import {
+  missingAppIdError,
+  resolveAppId,
+} from "../../../../tools/apps/resolve-app-id.js";
 import type {
   ToolContext,
   ToolExecutionResult,
@@ -13,5 +17,7 @@ export async function run(
   if (typeof input.change_summary === "string" && input.change_summary.trim()) {
     setAppCommitMessage(context.conversationId, input.change_summary.trim());
   }
-  return executeAppRefresh({ app_id: input.app_id as string }, appStore);
+  const appId = resolveAppId(input, context.conversationId);
+  if (!appId) return missingAppIdError();
+  return executeAppRefresh({ app_id: appId }, appStore);
 }