@vellumai/assistant 0.11.11-staging.2 → 0.11.11-staging.3

package/openapi.yaml

@@ -34306,6 +34306,67 @@ paths:
                   required:
                     - type
                     - fields
+                - type: object
+                  properties:
+                    type:
+                      type: string
+                      const: avatar_changed
+                    fields:
+                      type: object
+                      properties:
+                        action:
+                          type: string
+                          minLength: 1
+                          maxLength: 32
+                        kind:
+                          type: string
+                          minLength: 1
+                          maxLength: 16
+                        previous_kind:
+                          type: string
+                          minLength: 1
+                          maxLength: 16
+                        body_shape:
+                          type: string
+                          minLength: 1
+                          maxLength: 256
+                        eye_style:
+                          type: string
+                          minLength: 1
+                          maxLength: 256
+                        color:
+                          type: string
+                          minLength: 1
+                          maxLength: 256
+                        accent_hex:
+                          type: string
+                          minLength: 1
+                          maxLength: 7
+                        accent_source:
+                          type: string
+                          minLength: 1
+                          maxLength: 16
+                        client_os:
+                          type: string
+                          minLength: 1
+                          maxLength: 64
+                      required:
+                        - action
+                        - kind
+                        - previous_kind
+                      description:
+                        Wire event fields, excluding the daemon-stamped base fields (type, daemon_event_id, recorded_at,
+                        assistant_version).
+                    daemon_event_id:
+                      description:
+                        "Optional collapse key: rows sharing an id collapse downstream (e.g. a retried report). Defaults to a fresh
+                        per-row id."
+                      type: string
+                      minLength: 1
+                      maxLength: 128
+                  required:
+                    - type
+                    - fields
               type: object
       responses:
         "200":

package/package.json

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

package/src/__tests__/avatar-identity-sync.test.ts

@@ -3,6 +3,9 @@ import { describe, expect, mock, test } from "bun:test";
 mock.module("../platform/sync-avatar.js", () => ({
   syncAvatarToPlatform: () => {},
 }));
+mock.module("../telemetry/telemetry-events-outbox.js", () => ({
+  recordTelemetryEvent: () => ({ id: "evt", createdAt: 0 }),
+}));
 
 import type { AssistantEventEnvelope } from "../api/index.js";
 import { clearAvatar } from "../avatar/avatar-store.js";

package/src/__tests__/conversation-surfaces-settle-task-progress.test.ts

@@ -0,0 +1,218 @@
+/**
+ * Tests for `settleRunningTaskProgressSurfaces`: the turn-end floor that keeps
+ * a task_progress card from spinning after the turn it belonged to is over.
+ *
+ * Covers:
+ * - A card or step still `in_progress` becomes `pending`, via a real
+ *   `ui_surface_update` and the stored surface state.
+ * - Steps already `completed` or `failed` keep their status; nothing is
+ *   promoted to `completed`.
+ * - A card in a terminal state, a card with no running step, and non-card /
+ *   non-task_progress surfaces are left untouched.
+ * - A card from an earlier turn (absent from `currentTurnSurfaces`) is settled
+ *   too; the settle is idempotent.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import type pino from "pino";
+
+import type { AssistantEvent } from "../api/index.js";
+import type { Conversation } from "../daemon/conversation.js";
+import {
+  createSurfaceMutex,
+  settleRunningTaskProgressSurfaces,
+  surfaceProxyResolver,
+} from "../daemon/conversation-surfaces.js";
+import type {
+  CardSurfaceData,
+  SurfaceType,
+  UISurfaceUpdateEvent,
+} from "../daemon/message-protocol.js";
+import { asConversation } from "./helpers/mock-conversation.js";
+
+const noopLogger = {
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  debug: () => {},
+} as unknown as pino.Logger;
+
+function makeContext(sent: AssistantEvent[] = []): Conversation {
+  return asConversation({
+    conversationId: "session-1",
+    emit: (msg) => sent.push(msg),
+    pendingSurfaceActions: new Map<string, { surfaceType: SurfaceType }>(),
+    lastSurfaceAction: new Map<
+      string,
+      { actionId: string; data?: Record<string, unknown> }
+    >(),
+    surfaceState: new Map(),
+    surfaceUndoStacks: new Map<string, string[]>(),
+    accumulatedSurfaceState: new Map<string, Record<string, unknown>>(),
+    surfaceActionRequestIds: new Set<string>(),
+    currentTurnSurfaces: [],
+    isProcessing: () => false,
+    enqueueMessage: () => ({ queued: false, requestId: "req-1" }),
+    getQueueDepth: () => 0,
+    processMessage: async () => "ok",
+    withSurface: createSurfaceMutex(),
+  });
+}
+
+async function showTaskProgress(
+  ctx: Conversation,
+  templateData: Record<string, unknown>,
+): Promise<string> {
+  const result = await surfaceProxyResolver(ctx, "ui_show", {
+    surface_type: "card",
+    title: "Working",
+    data: { template: "task_progress", templateData },
+  });
+  expect(result.isError).toBe(false);
+  return (JSON.parse(result.content as string) as { surfaceId: string })
+    .surfaceId;
+}
+
+function updatesFor(sent: AssistantEvent[], surfaceId: string) {
+  return sent.filter(
+    (msg): msg is UISurfaceUpdateEvent =>
+      msg.type === "ui_surface_update" && msg.surfaceId === surfaceId,
+  );
+}
+
+function storedTemplateData(
+  ctx: Conversation,
+  surfaceId: string,
+): Record<string, unknown> {
+  const stored = ctx.surfaceState.get(surfaceId);
+  if (!stored || stored.surfaceType !== "card") {
+    throw new Error(`no stored card for ${surfaceId}`);
+  }
+  return (stored.data as CardSurfaceData).templateData as Record<
+    string,
+    unknown
+  >;
+}
+
+describe("settleRunningTaskProgressSurfaces", () => {
+  test("settles a running card and its running step to pending, keeping finished steps", async () => {
+    const sent: AssistantEvent[] = [];
+    const ctx = makeContext(sent);
+    const surfaceId = await showTaskProgress(ctx, {
+      title: "Send the follow-up",
+      status: "in_progress",
+      steps: [
+        { label: "Draft email", status: "completed" },
+        { label: "Send to contact", status: "in_progress" },
+        { label: "Log it", status: "pending" },
+        { label: "Archive", status: "failed" },
+      ],
+    });
+
+    settleRunningTaskProgressSurfaces(ctx, noopLogger);
+
+    const updates = updatesFor(sent, surfaceId);
+    expect(updates).toHaveLength(1);
+    const templateData = (updates[0].data as CardSurfaceData)
+      .templateData as Record<string, unknown>;
+    expect(templateData.status).toBe("pending");
+    expect(templateData.steps).toEqual([
+      { label: "Draft email", status: "completed" },
+      { label: "Send to contact", status: "pending" },
+      { label: "Log it", status: "pending" },
+      { label: "Archive", status: "failed" },
+    ]);
+    expect(storedTemplateData(ctx, surfaceId)).toEqual(templateData);
+  });
+
+  test("settles a running step under a card whose own status is already terminal", async () => {
+    const sent: AssistantEvent[] = [];
+    const ctx = makeContext(sent);
+    const surfaceId = await showTaskProgress(ctx, {
+      status: "failed",
+      steps: [{ label: "Only step", status: "in_progress" }],
+    });
+
+    settleRunningTaskProgressSurfaces(ctx, noopLogger);
+
+    const templateData = storedTemplateData(ctx, surfaceId);
+    expect(templateData.status).toBe("failed");
+    expect(templateData.steps).toEqual([
+      { label: "Only step", status: "pending" },
+    ]);
+  });
+
+  test("leaves a card alone when nothing on it is running", async () => {
+    const sent: AssistantEvent[] = [];
+    const ctx = makeContext(sent);
+    const completed = await showTaskProgress(ctx, {
+      status: "completed",
+      steps: [{ label: "Done", status: "completed" }],
+    });
+    const parked = await showTaskProgress(ctx, {
+      status: "pending",
+      steps: [{ label: "Later", status: "pending" }],
+    });
+    sent.length = 0;
+
+    settleRunningTaskProgressSurfaces(ctx, noopLogger);
+
+    expect(updatesFor(sent, completed)).toHaveLength(0);
+    expect(updatesFor(sent, parked)).toHaveLength(0);
+    expect(storedTemplateData(ctx, parked).status).toBe("pending");
+  });
+
+  test("ignores surfaces that are not task_progress cards", async () => {
+    const sent: AssistantEvent[] = [];
+    const ctx = makeContext(sent);
+    const plainCard = await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "card",
+      data: { title: "Note", body: "status: in_progress" },
+    });
+    const workResult = await surfaceProxyResolver(ctx, "ui_show", {
+      surface_type: "work_result",
+      data: { status: "in_progress", summary: "Crunching" },
+    });
+    expect(plainCard.isError).toBe(false);
+    expect(workResult.isError).toBe(false);
+    sent.length = 0;
+
+    settleRunningTaskProgressSurfaces(ctx, noopLogger);
+
+    expect(sent.filter((msg) => msg.type === "ui_surface_update")).toHaveLength(
+      0,
+    );
+  });
+
+  test("settles a card shown on an earlier turn and is idempotent", async () => {
+    const sent: AssistantEvent[] = [];
+    const ctx = makeContext(sent);
+    const surfaceId = await showTaskProgress(ctx, {
+      status: "in_progress",
+      steps: [{ label: "Step", status: "in_progress" }],
+    });
+    // The prior turn's snapshot has been persisted and cleared.
+    ctx.currentTurnSurfaces = [];
+    sent.length = 0;
+
+    settleRunningTaskProgressSurfaces(ctx, noopLogger);
+    settleRunningTaskProgressSurfaces(ctx, noopLogger);
+
+    expect(updatesFor(sent, surfaceId)).toHaveLength(1);
+    const templateData = storedTemplateData(ctx, surfaceId);
+    expect(templateData.status).toBe("pending");
+    expect(templateData.steps).toEqual([{ label: "Step", status: "pending" }]);
+  });
+
+  test("a card shown with a pending status keeps it", async () => {
+    const sent: AssistantEvent[] = [];
+    const ctx = makeContext(sent);
+    const surfaceId = await showTaskProgress(ctx, {
+      status: "pending",
+      steps: [{ label: "Step", status: "pending" }],
+    });
+
+    expect(storedTemplateData(ctx, surfaceId).status).toBe("pending");
+  });
+});

package/src/__tests__/surface-completion-nudge-hook.test.ts

@@ -12,6 +12,9 @@
  *   turn, and a non-main-agent call site.
  * - The signal is scoped to the current response cycle — a surface left open in
  *   a prior cycle (before the last genuine user prompt) does not trigger it.
+ * - The `surface_id` correlation reads the tool result the real `ui_show` tool
+ *   produces, including the update hint it carries on a task_progress card, so
+ *   the producer and this consumer cannot drift apart unnoticed.
  * - The one-shot bound is split across the two hooks: `post-model-call` marks it
  *   (nudging at most once per run) and `stop` clears it so the next run nudges
  *   afresh.
@@ -36,6 +39,7 @@ import {
   resetSurfaceCompletionNudgeStoreForTests,
 } from "../plugins/defaults/surface-completion-nudge/nudge-state-store.js";
 import type { ContentBlock, Message } from "../providers/types.js";
+import { uiShowTool } from "../tools/ui-surface/definitions.js";
 
 // ─── Fixtures ────────────────────────────────────────────────────────────────
 
@@ -54,7 +58,11 @@ let surfaceCounter = 0;
  * An assistant `ui_show` turn paired with its `{ surfaceId }` tool result.
  * Returns both messages plus the assigned surface id.
  */
-function showSurface(input: Record<string, unknown>): {
+function showSurface(
+  input: Record<string, unknown>,
+  resultContent: (surfaceId: string) => string = (surfaceId) =>
+    JSON.stringify({ surfaceId }),
+): {
   messages: Message[];
   surfaceId: string;
 } {
@@ -74,7 +82,7 @@ function showSurface(input: Record<string, unknown>): {
           {
             type: "tool_result",
             tool_use_id: toolUseId,
-            content: JSON.stringify({ surfaceId }),
+            content: resultContent(surfaceId),
           },
         ],
       },
@@ -82,6 +90,28 @@ function showSurface(input: Record<string, unknown>): {
   };
 }
 
+/**
+ * The tool result the real `ui_show` tool hands the model for `input`, with
+ * the daemon's proxy answering `{ surfaceId }`. Exercises the same code path
+ * production history is written from, hint and all.
+ */
+async function realUiShowResult(
+  input: Record<string, unknown>,
+  surfaceId: string,
+): Promise<string> {
+  const result = await uiShowTool.execute(input, {
+    conversationId: "conv-scn",
+    workingDir: "/tmp",
+    trustClass: "guardian",
+    proxyToolResolver: async () => ({
+      content: JSON.stringify({ surfaceId }),
+      isError: false,
+    }),
+  });
+  expect(result.isError).toBe(false);
+  return result.content as string;
+}
+
 function updateSurface(
   surfaceId: string,
   data: Record<string, unknown>,
@@ -190,6 +220,26 @@ describe("surface-completion-nudge — nudges on a dangling progress surface", (
     expect(isSurfaceCompletionNudged("conv-scn")).toBe(true);
   });
 
+  test("task_progress card shown via the real ui_show tool result → continue with nudge", async () => {
+    const input = taskProgressShow("in_progress");
+    const shown = showSurface(input, () => "placeholder");
+    const content = await realUiShowResult(input, shown.surfaceId);
+    // The real result carries the ui_update hint alongside the id.
+    expect(content).toContain("ui_update");
+    const result = shown.messages[1].content[0];
+    if (result.type !== "tool_result") {
+      throw new Error("expected a tool_result block");
+    }
+    result.content = content;
+    const ctx = makeCtx({
+      messages: [userPrompt("do the thing"), ...shown.messages],
+    });
+
+    await postModelCall(ctx);
+
+    expect(ctx.decision).toBe("continue");
+  });
+
   test("task_progress card shown with no explicit status → continue with nudge", async () => {
     const shown = showSurface(taskProgressShow());
     const ctx = makeCtx({

package/src/api/surface-show-result.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  parseSurfaceShowResultId,
+  withSurfaceShowNote,
+} from "./surface-show-result.js";
+
+const HINT_WITH_BRACES =
+  'As each step finishes, call ui_update { surface_id: "<id>", data: { templateData: { steps: [{ label: "x", status: "completed" }] } } }';
+
+describe("parseSurfaceShowResultId", () => {
+  test("reads the id from a bare envelope", () => {
+    expect(parseSurfaceShowResultId('{"surfaceId":"s-1"}')).toBe("s-1");
+  });
+
+  test("reads the id from an envelope carrying advisory fields", () => {
+    expect(
+      parseSurfaceShowResultId(
+        JSON.stringify({ surfaceId: "s-2", note: "hi", status: "displayed" }),
+      ),
+    ).toBe("s-2");
+  });
+
+  test("tolerates prose appended after the envelope, even prose with braces", () => {
+    expect(
+      parseSurfaceShowResultId(`{"surfaceId":"s-3"}\n\n${HINT_WITH_BRACES}`),
+    ).toBe("s-3");
+  });
+
+  test("ignores braces inside string values when finding the envelope end", () => {
+    expect(
+      parseSurfaceShowResultId(
+        '{"surfaceId":"s-4","note":"use { and } freely \\" }"} trailing',
+      ),
+    ).toBe("s-4");
+  });
+
+  test("returns undefined for non-envelope content", () => {
+    expect(parseSurfaceShowResultId("Surface updated")).toBeUndefined();
+    expect(parseSurfaceShowResultId("")).toBeUndefined();
+    expect(parseSurfaceShowResultId('{"surfaceId":1}')).toBeUndefined();
+    expect(parseSurfaceShowResultId('{"other":"x"}')).toBeUndefined();
+    expect(parseSurfaceShowResultId('{"surfaceId":"unterminated')).toBe(
+      undefined,
+    );
+  });
+});
+
+describe("withSurfaceShowNote", () => {
+  test("carries the note inside the envelope so the id stays parseable", () => {
+    const content = withSurfaceShowNote(
+      JSON.stringify({ surfaceId: "s-1" }),
+      HINT_WITH_BRACES,
+    );
+    expect(JSON.parse(content)).toEqual({
+      surfaceId: "s-1",
+      note: HINT_WITH_BRACES,
+    });
+    expect(parseSurfaceShowResultId(content)).toBe("s-1");
+  });
+
+  test("appends to an existing note rather than replacing it", () => {
+    const content = withSurfaceShowNote(
+      JSON.stringify({ surfaceId: "s-1", note: "first" }),
+      "second",
+    );
+    expect(JSON.parse(content)).toEqual({
+      surfaceId: "s-1",
+      note: "first\n\nsecond",
+    });
+  });
+
+  test("appends as prose when the content is not a surface envelope", () => {
+    expect(withSurfaceShowNote("Surface displayed", "note")).toBe(
+      "Surface displayed\n\nnote",
+    );
+  });
+});

package/src/api/surface-show-result.ts

@@ -0,0 +1,118 @@
+/**
+ * The `ui_show` tool-result envelope.
+ *
+ * A successful `ui_show` reports the created surface back to the model as a
+ * JSON object carrying the `surfaceId`, optionally alongside advisory fields
+ * (`status`, `note`, `message`) that coach the model on what to do next.
+ *
+ * The envelope is a contract, not just a string: the surface-completion nudge
+ * reads `surfaceId` back out of tool history to tell which progress surfaces
+ * the model left spinning. Producer and consumer therefore share this module,
+ * so guidance can only ever be added in a way the parser still understands.
+ */
+
+/** Fields a `ui_show` result envelope may carry beyond the surface id. */
+export interface SurfaceShowResult {
+  surfaceId: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Read the `surfaceId` out of a `ui_show` tool result, or `undefined` when the
+ * content is not a surface envelope.
+ *
+ * Trailing prose after the JSON object is tolerated: guidance belongs in a
+ * `note` field, but a caller that appends it instead must not silently cost
+ * the reader its `surfaceId`: losing the id makes a live progress surface
+ * invisible to the completion nudge, and the user watches it spin forever.
+ */
+export function parseSurfaceShowResultId(content: string): string | undefined {
+  const parsed = parseLeadingJsonObject(content);
+  return typeof parsed?.surfaceId === "string" ? parsed.surfaceId : undefined;
+}
+
+/**
+ * Attach advisory guidance to a `ui_show` result as a `note` field, keeping the
+ * content a single parseable JSON envelope. Content that is not a surface
+ * envelope (an error string, a non-JSON acknowledgment) falls back to appending
+ * the note as prose, which is still the right thing for the model to read.
+ */
+export function withSurfaceShowNote(content: string, note: string): string {
+  const parsed = parseLeadingJsonObject(content);
+  if (parsed === undefined || typeof parsed.surfaceId !== "string") {
+    return `${content}\n\n${note}`;
+  }
+  const existing = typeof parsed.note === "string" ? parsed.note : undefined;
+  return JSON.stringify({
+    ...parsed,
+    note: existing ? `${existing}\n\n${note}` : note,
+  });
+}
+
+/**
+ * Parse `content` as a JSON object, tolerating trailing text after the closing
+ * brace. Returns `undefined` for anything that is not a leading JSON object.
+ *
+ * The object's extent is found by matching braces rather than by scanning for
+ * the last `}`, because appended guidance routinely contains braces of its own
+ * (a worked `ui_update { ... }` example, say).
+ */
+function parseLeadingJsonObject(
+  content: string,
+): Record<string, unknown> | undefined {
+  const trimmed = content.trim();
+  const end = endOfLeadingJsonObject(trimmed);
+  if (end === undefined) {
+    return undefined;
+  }
+  try {
+    const parsed: unknown = JSON.parse(trimmed.slice(0, end + 1));
+    return parsed !== null && typeof parsed === "object"
+      ? (parsed as Record<string, unknown>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Index of the `}` closing the object that opens `text`, or `undefined` when
+ * `text` does not open with an object or the braces never balance. String
+ * literals (and their escapes) are skipped so braces inside values don't count.
+ */
+function endOfLeadingJsonObject(text: string): number | undefined {
+  if (!text.startsWith("{")) {
+    return undefined;
+  }
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (char === "\\") {
+        escaped = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === "{") {
+      depth++;
+      continue;
+    }
+    if (char === "}") {
+      depth--;
+      if (depth === 0) {
+        return i;
+      }
+    }
+  }
+  return undefined;
+}