@vellumai/assistant 0.11.8 → 0.11.9-staging.2

package/node_modules/@vellumai/service-contracts/src/reactions.ts

@@ -0,0 +1,60 @@
+/**
+ * Canonical vocabulary for a reaction's emoji, shared by every service that
+ * handles one: the gateway that normalizes it, the daemon that stores and
+ * projects it, and the web that renders it.
+ *
+ * The kind is said by the channel rather than inferred from how the emoji
+ * is spelled. Modelled on Zulip's `reaction_type`, the one surveyed system
+ * that separates the namespace from the name.
+ *
+ * `shortcode` is a name in a channel's own namespace whose kind the channel
+ * does not disclose: Slack sends `+1` for the standard emoji and `blob_wave`
+ * for a workspace upload with nothing to tell them apart, and only the
+ * workspace token can resolve the second. It is a distinct kind from
+ * `unicode`, not a stand-in for an unknown one.
+ */
+import { z } from "zod";
+
+export const REACTION_EMOJI_KINDS = ["unicode", "shortcode", "custom"] as const;
+export type ReactionEmojiKind = (typeof REACTION_EMOJI_KINDS)[number];
+
+/**
+ * The typed emoji fields every schema that carries a reaction spreads in,
+ * so the wire contract, the stored envelopes, and the response projection
+ * describe one shape. Optional throughout: a persisted row or a replayed
+ * payload may carry only the spelling.
+ */
+export const ReactionEmojiFieldsSchema = z.object({
+  /** Which namespace the emoji was drawn from. */
+  emojiKind: z.enum(REACTION_EMOJI_KINDS).optional(),
+  /**
+   * The emoji's name in that namespace: the character itself for `unicode`,
+   * the bare name for `shortcode` and `custom`. Never a mention form.
+   */
+  emojiName: z.string().optional(),
+  /** The channel's id for a `custom` emoji, absent for every other kind. */
+  emojiId: z.string().optional(),
+  /** Whether a `custom` emoji animates. Absent for every other kind. */
+  emojiAnimated: z.boolean().optional(),
+});
+export type ReactionEmojiFields = z.infer<typeof ReactionEmojiFieldsSchema>;
+
+/**
+ * The typed emoji fields a source actually carries, with undefined ones
+ * omitted: an absent key and a present-but-undefined one serialize alike, but the
+ * stored envelope and the response should carry only what was declared. Every writer of a reaction shape (the wire
+ * payload, both stored envelopes, the response projection) copies the
+ * fields through this rather than restating the four-way pick.
+ */
+export function pickReactionEmojiFields(
+  source: ReactionEmojiFields,
+): ReactionEmojiFields {
+  return {
+    ...(source.emojiKind !== undefined ? { emojiKind: source.emojiKind } : {}),
+    ...(source.emojiName !== undefined ? { emojiName: source.emojiName } : {}),
+    ...(source.emojiId !== undefined ? { emojiId: source.emojiId } : {}),
+    ...(source.emojiAnimated !== undefined
+      ? { emojiAnimated: source.emojiAnimated }
+      : {}),
+  };
+}

package/openapi.yaml

@@ -3,7 +3,7 @@
 openapi: 3.1.0
 info:
   title: Vellum Assistant API
-  version: 0.11.8
+  version: 0.11.9
   description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server.
 servers:
   - url: http://127.0.0.1:7821
@@ -4076,6 +4076,59 @@ paths:
       responses:
         "200":
           description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  bound:
+                    type: boolean
+                  channel:
+                    type: string
+                    enum:
+                      - telegram
+                      - phone
+                      - vellum
+                      - whatsapp
+                      - slack
+                      - email
+                      - platform
+                      - a2a
+                      - discord
+                      - plugin
+                  assistantId:
+                    type: string
+                  hasPendingChallenge:
+                    type: boolean
+                  guardianExternalUserId:
+                    type: string
+                  guardianDeliveryChatId:
+                    type: string
+                  guardianUsername:
+                    type: string
+                  guardianDisplayName:
+                    type: string
+                  verificationSessionId:
+                    type: string
+                  expiresAt:
+                    type: number
+                  nextResendAt:
+                    anyOf:
+                      - type: number
+                      - type: "null"
+                  sendCount:
+                    type: number
+                  pendingBootstrap:
+                    type: boolean
+                required:
+                  - success
+                  - bound
+                  - channel
+                  - assistantId
+                  - hasPendingChallenge
+                additionalProperties: false
   /v1/channels/available:
     get:
       operationId: channels_available_get
@@ -4210,6 +4263,18 @@ paths:
                         - removed
                     emoji:
                       type: string
+                    emojiKind:
+                      type: string
+                      enum:
+                        - unicode
+                        - shortcode
+                        - custom
+                    emojiName:
+                      type: string
+                    emojiId:
+                      type: string
+                    emojiAnimated:
+                      type: boolean
                     targetMessageId:
                       type: string
                   required:
@@ -8136,6 +8201,54 @@ paths:
           description: The assistant is currently responding
         "422":
           description: No user message exists to retry from
+  /v1/conversations/{id}/sight-frame:
+    post:
+      operationId: conversations_by_id_sightframe_post
+      summary: Persist an ambient camera frame
+      description:
+        Add an already-uploaded camera frame to a conversation as its own message, tagged so retention can age the
+        image out of the model's context while the transcript keeps it. No reply is generated. Returns persisted=false
+        when the frame was dropped, in which case the assistant owns the upload and there is nothing to clean up.
+      tags:
+        - conversations
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                attachmentId:
+                  type: string
+                  description: Id of the uploaded attachment holding the frame.
+              required:
+                - attachmentId
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  persisted:
+                    type: boolean
+                  messageId:
+                    description: The message the frame landed on, when one was written.
+                    type: string
+                required:
+                  - persisted
+                additionalProperties: false
+        "400":
+          description: Missing or empty attachmentId
+        "404":
+          description: Conversation not found
   /v1/conversations/{id}/slash:
     post:
       operationId: conversations_by_id_slash_post
@@ -9865,7 +9978,11 @@ paths:
         unassigned conversations, Chats) with total and unread counts and no conversation rows. Lets a client know which
         sections exist, and what their badges say, without fetching any conversation list. Totals follow the standard
         listing visibility; unread applies the same rules as GET /v1/conversations/unread-count scoped to the section.
-        Chats is always present, even at zero: it is the leftover bucket and renders regardless."
+        Chats is always present, even at zero: it is the leftover bucket and renders regardless. Under the
+        `assistant-initiated-threads` flag an `assistant` section is also present at every count — the threads the
+        assistant started on its own, selectable as a list via `groupId=system:assistant` — and its rows are withheld
+        from Chats so the buckets stay disjoint. With the flag off no `assistant` row is emitted and those conversations
+        are counted in Chats as before."
       tags:
         - conversations
       responses:
@@ -9894,6 +10011,20 @@ paths:
                             - total
                             - unread
                           additionalProperties: false
+                        - type: object
+                          properties:
+                            kind:
+                              type: string
+                              const: assistant
+                            total:
+                              type: number
+                            unread:
+                              type: number
+                          required:
+                            - kind
+                            - total
+                            - unread
+                          additionalProperties: false
                         - type: object
                           properties:
                             kind:
@@ -10966,7 +11097,9 @@ paths:
                     description: Processed text output
                   mode:
                     type: string
-                    description: "Detected mode: dictation, command, or action"
+                    description:
+                      "Detected mode: dictation, command, action, or question (selected text the words asked about rather than
+                      changed; text is the transcription)"
                   actionPlan:
                     description: Action plan (only when mode is action)
                     type: string
@@ -20963,6 +21096,18 @@ paths:
                           properties:
                             emoji:
                               type: string
+                            emojiKind:
+                              type: string
+                              enum:
+                                - unicode
+                                - shortcode
+                                - custom
+                            emojiName:
+                              type: string
+                            emojiId:
+                              type: string
+                            emojiAnimated:
+                              type: boolean
                             op:
                               type: string
                               enum:
@@ -21032,6 +21177,18 @@ paths:
                               properties:
                                 emoji:
                                   type: string
+                                emojiKind:
+                                  type: string
+                                  enum:
+                                    - unicode
+                                    - shortcode
+                                    - custom
+                                emojiName:
+                                  type: string
+                                emojiId:
+                                  type: string
+                                emojiAnimated:
+                                  type: boolean
                                 op:
                                   type: string
                                   enum:
@@ -21050,6 +21207,8 @@ paths:
                             - channelId
                             - channelTs
                           additionalProperties: false
+                        deletedAt:
+                          type: number
                         queueStatus:
                           type: string
                           enum:
@@ -24269,7 +24428,9 @@ paths:
     post:
       operationId: platform_connect_post
       summary: Connect to the Vellum Platform
-      description: Checks existing credentials and emits the show_platform_login signal for connected clients to show a login UI.
+      description:
+        Checks whether the stored platform credentials still connect. Reports a stored key the platform rejects as
+        credentialRejected, so the caller can direct the user to sign in again and replace it.
       tags:
         - platform
       responses:
@@ -24286,6 +24447,8 @@ paths:
                     type: string
                   showPlatformLogin:
                     type: boolean
+                  credentialRejected:
+                    type: boolean
                 additionalProperties: false
   /v1/platform/credits:
     get:
@@ -24654,6 +24817,32 @@ paths:
                   - package
                   - entitlements
                 additionalProperties: false
+  /v1/platform/verify-credential:
+    post:
+      operationId: platform_verifycredential_post
+      summary: Verify the Vellum-managed credential against the platform
+      description:
+        Asks the platform whether the stored assistant API key authenticates. POST because it performs a check; the
+        result is returned, not stored.
+      tags:
+        - platform
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    enum:
+                      - valid
+                      - rejected
+                      - unknown
+                required:
+                  - status
+                additionalProperties: false
   /v1/playground/seed-conversation:
     post:
       operationId: playground_seedconversation_post

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.8",
+  "version": "0.11.9-staging.2",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -74,7 +74,7 @@
     "remark-parse": "11.0.0",
     "rrule": "2.8.1",
     "semver": "7.8.0",
-    "sharp": "0.34.5",
+    "sharp": "0.35.4",
     "stemmer": "2.0.1",
     "tar-stream": "3.1.7",
     "tldts": "7.0.25",

package/src/__tests__/access-request-card-view.test.ts

@@ -2,7 +2,8 @@ import { describe, expect, test } from "bun:test";
 
 import {
   buildAccessRequestCardView,
-  buildAccessRequestContractText,
+  buildAccessRequestContextText,
+  buildAccessRequestReplyMechanics,
   parseAccessRequestPayload,
 } from "../notifications/access-request-copy.js";
 
@@ -111,10 +112,10 @@ describe("admitted-mode introduction nudge copy", () => {
       senderIdentifier: "Alice",
       sourceChannel: "telegram",
     };
-    expect(buildAccessRequestContractText(base)).toContain(
+    expect(buildAccessRequestContextText(base)).toContain(
       "is requesting access to the assistant.",
     );
-    const admitted = buildAccessRequestContractText({
+    const admitted = buildAccessRequestContextText({
       ...base,
       trigger: "admitted",
     });
@@ -122,8 +123,8 @@ describe("admitted-mode introduction nudge copy", () => {
     expect(admitted).not.toContain("is requesting access");
   });
 
-  test("admitted contract text keeps the decision directives", () => {
-    const text = buildAccessRequestContractText({
+  test("admitted reply mechanics keep the decision directives", () => {
+    const text = buildAccessRequestReplyMechanics({
       actorDisplayName: "Alice",
       sourceChannel: "telegram",
       requestCode: "ab12cd",

package/src/__tests__/access-request-seed-content-blocks.test.ts

@@ -136,10 +136,13 @@ describe("buildAccessRequestSeedContentBlocks", () => {
     );
   });
 
-  test("text fallback block contains contract text", () => {
+  test("text fallback block is the text-only rendering: context, invite directive, and the typed directive", () => {
     const textBlock = textOf(buildAccessRequestSeedContentBlocks(basePayload));
     expect(textBlock.text).toContain("requesting access to the assistant");
-    expect(textBlock.text).toContain("ABC123");
+    expect(textBlock.text).toContain('Reply "open invite flow"');
+    // A client that cannot draw the card's buttons still gets the directive.
+    expect(textBlock.text).toContain('"ABC123 trust"');
+    expect(textBlock.text).toContain('"ABC123 block"');
   });
 
   test("body shows fallback when no preview/warnings/permalink", () => {

package/src/__tests__/agent-loop-mutable-latest-user-message.test.ts

@@ -1,16 +1,9 @@
 /**
- * Verifies how the loop derives the `mutableLatestUserMessage` cache-anchor
- * signal on `SendMessageOptions.config`.
+ * Verifies that a persisted memory-v3 spotlight already in history is sent
+ * as-is and does not flag the turn-start message as volatile.
  *
- * The signal means "the latest user message's bytes do not recur next turn", so
- * it is set from the history actually being sent: only when the latest user
- * message carries a memory-v3 `<memory_spotlight>` block, the one injected
- * block that is strip-and-replaced on the tail every turn. Every other injected
- * block is frozen into history and re-renders byte-identically, so turns
- * without a spotlight keep a normal cache anchor even when memory-v3 is live.
- *
- * When no spotlight is present the field is omitted entirely (not `false`) so
- * the wire stays byte-identical for conversations that never see one.
+ * Spotlight stays on the user message that was sent. The loop must not
+ * attach, strip, or mark that message mutable.
  */
 
 import { describe, expect, test } from "bun:test";
@@ -25,17 +18,18 @@ import type {
   ToolDefinition,
 } from "../providers/types.js";
 
+const spotlightText = wrapMemorySpotlightBlock("recalled: Alice's plan");
+
 const userMessage: Message = {
   role: "user",
   content: [{ type: "text", text: "hi" }],
 };
 
-/** A user turn whose tail block is the ephemeral memory-v3 spotlight. */
-const spotlightUserMessage: Message = {
+const userMessageWithSpotlight: Message = {
   role: "user",
   content: [
     { type: "text", text: "hi" },
-    { type: "text", text: wrapMemorySpotlightBlock("recalled: Alice's plan") },
+    { type: "text", text: spotlightText },
   ],
 };
 
@@ -64,22 +58,25 @@ function toolUseResponse(
 function makeRecordingProvider(responses: ProviderResponse[]): {
   provider: Provider;
   configs: () => Array<Record<string, unknown> | undefined>;
+  sent: () => Message[][];
 } {
   const configs: Array<Record<string, unknown> | undefined> = [];
+  const sent: Message[][] = [];
   let i = 0;
   const provider: Provider = {
     name: "mock",
     async sendMessage(
-      _messages: Message[],
+      messages: Message[],
       options?: SendMessageOptions,
     ): Promise<ProviderResponse> {
+      sent.push(messages);
       configs.push(options?.config as Record<string, unknown> | undefined);
       const response = responses[i] ?? responses[responses.length - 1];
       i++;
       return response;
     },
   };
-  return { provider, configs: () => configs };
+  return { provider, configs: () => configs, sent: () => sent };
 }
 
 const echoTool: ToolDefinition = {
@@ -91,34 +88,11 @@ const echoTool: ToolDefinition = {
   },
 };
 
-describe("AgentLoop.run: mutableLatestUserMessage from spotlight presence", () => {
-  test("sets mutableLatestUserMessage when the latest user message carries a spotlight block", async () => {
-    // GIVEN a provider that records the config of each LLM call
-    const { provider, configs } = makeRecordingProvider([textResponse("done")]);
-    const loop = new AgentLoop({
-      provider,
-      systemPrompt: "system",
-      conversationId: "test-conversation",
-      config: { maxTokens: 1024 },
-    });
-
-    // WHEN the loop runs over a history whose tail carries the spotlight
-    await loop.run({
-      requestId: "test-request",
-      messages: [spotlightUserMessage],
-      onEvent: () => {},
-      trust: { sourceChannel: "vellum", trustClass: "unknown" },
-      callSite: "mainAgent",
-    });
-
-    // THEN the send carries the cache-anchor signal
-    expect(configs()).toHaveLength(1);
-    expect(configs()[0]?.mutableLatestUserMessage).toBe(true);
-  });
-
-  test("omits mutableLatestUserMessage when the latest user message carries no spotlight", async () => {
-    // GIVEN a provider that records the config of each LLM call
-    const { provider, configs } = makeRecordingProvider([textResponse("hi")]);
+describe("AgentLoop.run: persisted spotlight in history", () => {
+  test("sends a spotlight already in history and does not flag the turn-start as volatile", async () => {
+    const { provider, configs, sent } = makeRecordingProvider([
+      textResponse("done"),
+    ]);
     const loop = new AgentLoop({
       provider,
       systemPrompt: "system",
@@ -126,24 +100,26 @@ describe("AgentLoop.run: mutableLatestUserMessage from spotlight presence", () =
       config: { maxTokens: 1024 },
     });
 
-    // WHEN the loop runs over a spotlight-free history: the shape memory-v3
-    // produces whenever it selects nothing to spotlight
-    await loop.run({
+    const result = await loop.run({
       requestId: "test-request",
-      messages: [userMessage],
+      messages: [userMessageWithSpotlight],
       onEvent: () => {},
       trust: { sourceChannel: "vellum", trustClass: "unknown" },
       callSite: "mainAgent",
     });
 
-    // THEN the field is omitted entirely, not carried as false/undefined
-    expect(configs()).toHaveLength(1);
+    expect(sent()).toHaveLength(1);
+    expect(sent()[0]![0]!.content).toEqual(userMessageWithSpotlight.content);
+    expect(result.history[0]!.content).toEqual(
+      userMessageWithSpotlight.content,
+    );
     expect("mutableLatestUserMessage" in (configs()[0] ?? {})).toBe(false);
   });
 
-  test("a text block merely opening with the spotlight tag is not treated as volatile", async () => {
-    // GIVEN a user message discussing the marker rather than carrying one
-    const { provider, configs } = makeRecordingProvider([textResponse("hi")]);
+  test("does not set mutableLatestUserMessage when history has no spotlight", async () => {
+    const { provider, sent, configs } = makeRecordingProvider([
+      textResponse("hi"),
+    ]);
     const loop = new AgentLoop({
       provider,
       systemPrompt: "system",
@@ -151,34 +127,20 @@ describe("AgentLoop.run: mutableLatestUserMessage from spotlight presence", () =
       config: { maxTokens: 1024 },
     });
 
-    // WHEN the loop runs
     await loop.run({
       requestId: "test-request",
-      messages: [
-        {
-          role: "user",
-          content: [
-            {
-              type: "text",
-              text: "<memory_spotlight>\nwhat does this tag do?",
-            },
-          ],
-        },
-      ],
+      messages: [userMessage],
       onEvent: () => {},
       trust: { sourceChannel: "vellum", trustClass: "unknown" },
       callSite: "mainAgent",
     });
 
-    // THEN the unterminated wrapper does not count: matching the full-wrapper
-    // requirement the per-turn strip applies
-    expect(configs()).toHaveLength(1);
+    expect(sent()[0]).toEqual([userMessage]);
     expect("mutableLatestUserMessage" in (configs()[0] ?? {})).toBe(false);
   });
 
-  test("the signal holds for every request in a tool loop", async () => {
-    // GIVEN a spotlight-bearing opening message and a tool round-trip
-    const { provider, configs } = makeRecordingProvider([
+  test("keeps a persisted spotlight on the opening user message through a tool loop", async () => {
+    const { provider, sent, configs } = makeRecordingProvider([
       toolUseResponse("t1", "echo", { value: "first" }),
       textResponse("done"),
     ]);
@@ -191,22 +153,21 @@ describe("AgentLoop.run: mutableLatestUserMessage from spotlight presence", () =
       toolExecutor: async () => ({ content: "ok", isError: false }),
     });
 
-    // WHEN the loop runs
-    await loop.run({
+    const result = await loop.run({
       requestId: "test-request",
-      messages: [spotlightUserMessage],
+      messages: [userMessageWithSpotlight],
       onEvent: () => {},
       trust: { sourceChannel: "vellum", trustClass: "unknown" },
       callSite: "mainAgent",
     });
 
-    // THEN both calls report the turn as volatile. The signal describes the
-    // turn-starting message, not whichever user message happens to be last, so
-    // the trailing tool-result turn does not clear it. Holding it steady is
-    // what keeps the provider marking that one block at a single TTL for the
-    // whole turn instead of writing it twice.
-    expect(configs()).toHaveLength(2);
-    expect(configs()[0]?.mutableLatestUserMessage).toBe(true);
-    expect(configs()[1]?.mutableLatestUserMessage).toBe(true);
+    expect(sent()).toHaveLength(2);
+    expect(sent()[0]![0]!.content).toEqual(userMessageWithSpotlight.content);
+    expect(sent()[1]![0]!.content).toEqual(userMessageWithSpotlight.content);
+    expect(result.history[0]!.content).toEqual(
+      userMessageWithSpotlight.content,
+    );
+    expect("mutableLatestUserMessage" in (configs()[0] ?? {})).toBe(false);
+    expect("mutableLatestUserMessage" in (configs()[1] ?? {})).toBe(false);
   });
 });

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

@@ -26,7 +26,7 @@ afterAll(() => {
 });
 
 describe("always-loaded tool count", () => {
-  test("should be exactly 10 with recall occupying the existing slot", async () => {
+  test("should be exactly 11 with recall occupying the existing slot", async () => {
     await initializeTools();
     const allDefs = getAllToolDefinitions();
 
@@ -47,6 +47,11 @@ describe("always-loaded tool count", () => {
     // Host tools (host_bash, host_file_*) are excluded when no client is
     // connected — without a human in the loop, the guardian auto-approve
     // path would allow unchecked host command execution.
+    //
+    // `watch_retro_report` is here for the same reason the ui_surface tools are
+    // NOT: a watch retrospective runs clientless, so it can only report through
+    // a tool that survives this baseline. Its description and schema are kept
+    // deliberately terse because that is the cost of the slot.
     const expectedNames = [
       "bash",
       "file_edit",
@@ -56,12 +61,13 @@ describe("always-loaded tool count", () => {
       "remember",
       "skill_execute",
       "skill_load",
+      "watch_retro_report",
       "web_fetch",
       "web_search",
     ].sort();
 
     expect(activeNames).toEqual(expectedNames);
     expect(activeNames.filter((name) => name === "recall")).toHaveLength(1);
-    expect(activeTools.length).toBe(10);
+    expect(activeTools.length).toBe(11);
   });
 });