@vellumai/assistant 0.11.6 → 0.11.7-staging.2

package/src/persistence/lifecycle-events-store.ts

@@ -1,5 +1,8 @@
 import { recordTelemetryEvent } from "../telemetry/telemetry-events-outbox.js";
-import type { LifecycleTelemetryEvent } from "../telemetry/types.js";
+import type {
+  LifecycleTelemetryEvent,
+  TelemetryEventBase,
+} from "../telemetry/types.js";
 import { APP_VERSION } from "../version.js";
 
 export interface LifecycleEvent {
@@ -8,6 +11,68 @@ export interface LifecycleEvent {
   createdAt: number;
 }
 
+/**
+ * Optional typed attributes a lifecycle event carries alongside its name.
+ *
+ * Every one is nullable and optional on the wire, so a caller with nothing to
+ * say omits it and a platform that predates the field ignores it. They exist
+ * so grouping dimensions (risk, access preset, surface) are columns rather
+ * than substrings of `event_name`, which the server caps at 64 chars.
+ */
+export interface LifecycleEventAttributes {
+  /**
+   * Tool the event is about. The stable join key between a permission prompt
+   * and its decision: `event_name` embeds a truncated tool name, this does not.
+   */
+  toolName?: string;
+  /** Classified risk of the invocation ("low" | "medium" | "high"). */
+  riskLevel?: string;
+  /** Auto-approve threshold (access preset) in effect for the invocation. */
+  riskThreshold?: string;
+  /** Channel the event's turn runs on ("vellum", "slack", "telegram", ...). */
+  surface?: string;
+  /**
+   * Parent conversation. Rides the same `share_analytics` gate as the
+   * conversation ids on `turn` / `llm_usage` / `tool_executed`, and scopes the
+   * pending outbox row so deleting the conversation deletes the row with it.
+   */
+  conversationId?: string;
+}
+
+/** Lifecycle wire payload minus the fields `recordTelemetryEvent` stamps. */
+type LifecycleFields = Omit<LifecycleTelemetryEvent, keyof TelemetryEventBase>;
+
+/**
+ * Assemble the lifecycle wire fields, omitting attributes the caller left
+ * unset so a plain `app_open` payload stays exactly as small as it was.
+ *
+ * An empty attribute is omitted rather than sent: the wire schema requires at
+ * least one character, and a single failing field makes the server drop the
+ * whole event silently.
+ */
+function buildLifecycleFields(
+  eventName: string,
+  attributes: LifecycleEventAttributes,
+): LifecycleFields {
+  const fields: LifecycleFields = { event_name: eventName };
+  if (attributes.toolName) {
+    fields.tool_name = attributes.toolName;
+  }
+  if (attributes.riskLevel) {
+    fields.risk_level = attributes.riskLevel;
+  }
+  if (attributes.riskThreshold) {
+    fields.risk_threshold = attributes.riskThreshold;
+  }
+  if (attributes.surface) {
+    fields.surface = attributes.surface;
+  }
+  if (attributes.conversationId) {
+    fields.conversation_id = attributes.conversationId;
+  }
+  return fields;
+}
+
 /**
  * Wire shape of one lifecycle event, for callers that insert outbox rows via
  * raw SQL (conversation-crud's clearAll audit path). Mirrors the shape
@@ -32,9 +97,14 @@ export function buildLifecycleTelemetryEvent(
  * Record a lifecycle event (e.g. app_open, hatch) into the `telemetry_events`
  * outbox. Consent gating and degraded-mode `null` are `recordTelemetryEvent`'s.
  */
-export function recordLifecycleEvent(eventName: string): LifecycleEvent | null {
-  const recorded = recordTelemetryEvent("lifecycle", {
-    event_name: eventName,
-  });
+export function recordLifecycleEvent(
+  eventName: string,
+  attributes: LifecycleEventAttributes = {},
+): LifecycleEvent | null {
+  const recorded = recordTelemetryEvent(
+    "lifecycle",
+    buildLifecycleFields(eventName, attributes),
+    { conversationId: attributes.conversationId ?? null },
+  );
   return recorded ? { ...recorded, eventName } : null;
 }

package/src/platform/platform-patch-queue.test.ts

@@ -0,0 +1,368 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  setSystemTime,
+  test,
+} from "bun:test";
+
+let mockClient: {
+  baseUrl: string;
+  platformAssistantId: string;
+  fetch: (path: string, init: RequestInit) => Promise<Response>;
+} | null;
+
+mock.module("./client.js", () => ({
+  VellumPlatformClient: { create: async () => mockClient },
+}));
+
+import { getLogger } from "../util/logger.js";
+import {
+  createPlatformPatchQueue,
+  type SyncedKey,
+} from "./platform-patch-queue.js";
+
+interface Patch {
+  path: string;
+  body: { value: string };
+}
+
+let patches: Patch[];
+let respond: () => Response;
+let builds: number;
+let queues: Array<{ dispose: () => void }>;
+
+function makeClient(assistantId = "asst-1", baseUrl = "https://platform.a") {
+  return {
+    baseUrl,
+    platformAssistantId: assistantId,
+    fetch: async (path: string, init: RequestInit) => {
+      patches.push({ path, body: JSON.parse(init.body as string) });
+      return respond();
+    },
+  };
+}
+
+function makeQueue(
+  opts: {
+    loadSyncedKey?: () => SyncedKey | null;
+    saveSyncedKey?: (synced: SyncedKey) => void;
+    maxAgeMs?: number;
+    retryDelaysMs?: number[];
+  } = {},
+) {
+  const queue = createPlatformPatchQueue<string | undefined>({
+    log: getLogger("test"),
+    label: "value",
+    buildPayload: (value) => {
+      builds += 1;
+      return value === undefined ? undefined : { key: value, body: { value } };
+    },
+    ...opts,
+  });
+  queues.push(queue);
+  return queue;
+}
+
+async function settle(): Promise<void> {
+  for (let i = 0; i < 10; i++) {
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+describe("createPlatformPatchQueue", () => {
+  beforeEach(() => {
+    patches = [];
+    builds = 0;
+    respond = () => new Response("{}", { status: 200 });
+    mockClient = makeClient();
+    queues = [];
+  });
+
+  afterEach(() => {
+    for (const queue of queues) {
+      queue.dispose();
+    }
+  });
+
+  test("PATCHes once and dedups an unchanged key", async () => {
+    const queue = makeQueue();
+    queue.enqueue("a");
+    await settle();
+    queue.enqueue("a");
+    await settle();
+
+    expect(patches).toEqual([
+      { path: "/v1/assistants/asst-1/", body: { value: "a" } },
+    ]);
+  });
+
+  test("re-registering to another assistant id or base URL re-sends", async () => {
+    const queue = makeQueue();
+    queue.enqueue("a");
+    await settle();
+    mockClient = makeClient("asst-2");
+    queue.enqueue("a");
+    await settle();
+    mockClient = makeClient("asst-2", "https://platform.b");
+    queue.enqueue("a");
+    await settle();
+    queue.enqueue("a");
+    await settle();
+
+    expect(patches.map((p) => p.path)).toEqual([
+      "/v1/assistants/asst-1/",
+      "/v1/assistants/asst-2/",
+      "/v1/assistants/asst-2/",
+    ]);
+  });
+
+  test("rapid enqueues collapse into one PATCH carrying the newest payload", async () => {
+    const queue = makeQueue();
+    queue.enqueue("a");
+    queue.enqueue("b");
+    queue.enqueue("c");
+    await settle();
+
+    expect(patches.map((p) => p.body.value)).toEqual(["c"]);
+    expect(builds).toBe(1);
+  });
+
+  test("an undefined payload, missing client, or missing assistant id skips", async () => {
+    const queue = makeQueue();
+    queue.enqueue(undefined);
+    await settle();
+    mockClient = null;
+    queue.enqueue("a");
+    await settle();
+    mockClient = makeClient("");
+    queue.enqueue("a");
+    await settle();
+
+    expect(patches).toHaveLength(0);
+    expect(builds).toBe(1);
+  });
+
+  test("a failed PATCH does not dedup the next attempt", async () => {
+    const queue = makeQueue();
+    respond = () => new Response("nope", { status: 500 });
+    queue.enqueue("a");
+    await settle();
+    respond = () => new Response("{}", { status: 200 });
+    queue.enqueue("a");
+    await settle();
+    queue.enqueue("a");
+    await settle();
+
+    expect(patches).toHaveLength(2);
+  });
+
+  test("a thrown fetch is swallowed and retried on the next enqueue", async () => {
+    const queue = makeQueue();
+    mockClient = {
+      ...makeClient(),
+      fetch: async () => {
+        throw new Error("boom");
+      },
+    };
+    queue.enqueue("a");
+    await settle();
+    mockClient = makeClient();
+    queue.enqueue("a");
+    await settle();
+
+    expect(patches).toHaveLength(1);
+  });
+
+  test("seeds the dedup key from loadSyncedKey and saves each success", async () => {
+    const saved: SyncedKey[] = [];
+    const queue = makeQueue({
+      loadSyncedKey: () => ({
+        key: "https://platform.a|asst-1|a",
+        syncedAt: Date.now(),
+      }),
+      saveSyncedKey: (synced) => saved.push(synced),
+    });
+    queue.enqueue("a");
+    await settle();
+    queue.enqueue("b");
+    await settle();
+
+    expect(patches.map((p) => p.body.value)).toEqual(["b"]);
+    expect(saved).toEqual([
+      { key: "https://platform.a|asst-1|b", syncedAt: expect.any(Number) },
+    ]);
+  });
+
+  test("a matching key older than maxAgeMs re-sends in-process", async () => {
+    const saved: SyncedKey[] = [];
+    const queue = makeQueue({
+      maxAgeMs: 1000,
+      saveSyncedKey: (synced) => saved.push(synced),
+    });
+    const start = Date.now();
+    setSystemTime(new Date(start));
+    try {
+      queue.enqueue("a");
+      await settle();
+      setSystemTime(new Date(start + 999));
+      queue.enqueue("a");
+      await settle();
+      setSystemTime(new Date(start + 1000));
+      queue.enqueue("a");
+      await settle();
+      queue.enqueue("a");
+      await settle();
+    } finally {
+      setSystemTime();
+    }
+
+    expect(patches).toHaveLength(2);
+    expect(saved.map((s) => s.syncedAt)).toEqual([start, start + 1000]);
+  });
+
+  test("a seeded key older than maxAgeMs re-sends", async () => {
+    const queue = makeQueue({
+      maxAgeMs: 1000,
+      loadSyncedKey: () => ({
+        key: "https://platform.a|asst-1|a",
+        syncedAt: Date.now() - 1000,
+      }),
+    });
+    queue.enqueue("a");
+    await settle();
+
+    expect(patches).toHaveLength(1);
+  });
+
+  test("re-sends at expiry with no enqueue call, and dispose cancels that", async () => {
+    const queue = makeQueue({ maxAgeMs: 300 });
+    queue.enqueue("a");
+    await settle();
+    expect(patches).toHaveLength(1);
+
+    await new Promise((r) => setTimeout(r, 300));
+    await settle();
+    expect(patches).toHaveLength(2);
+    expect(builds).toBe(2);
+
+    queue.dispose();
+    await new Promise((r) => setTimeout(r, 300));
+    await settle();
+    expect(patches).toHaveLength(2);
+  });
+
+  test("a seeded, still-fresh key arms the expiry re-send", async () => {
+    const queue = makeQueue({
+      maxAgeMs: 300,
+      loadSyncedKey: () => ({
+        key: "https://platform.a|asst-1|a",
+        syncedAt: Date.now(),
+      }),
+    });
+    queue.enqueue("a");
+    await settle();
+    expect(patches).toHaveLength(0);
+
+    await new Promise((r) => setTimeout(r, 300));
+    await settle();
+    expect(patches).toHaveLength(1);
+  });
+
+  test("a failed PATCH retries on backoff and dedups after the retry succeeds", async () => {
+    const queue = makeQueue({ retryDelaysMs: [100, 100, 100] });
+    respond = () => new Response("nope", { status: 500 });
+    queue.enqueue("a");
+    await settle();
+    expect(patches).toHaveLength(1);
+
+    respond = () => new Response("{}", { status: 200 });
+    await new Promise((r) => setTimeout(r, 100));
+    await settle();
+    expect(patches).toHaveLength(2);
+
+    await new Promise((r) => setTimeout(r, 100));
+    await settle();
+    queue.enqueue("a");
+    await settle();
+    expect(patches).toHaveLength(2);
+  });
+
+  test("a thrown fetch retries on backoff", async () => {
+    const queue = makeQueue({ retryDelaysMs: [100] });
+    mockClient = {
+      ...makeClient(),
+      fetch: async () => {
+        throw new Error("boom");
+      },
+    };
+    queue.enqueue("a");
+    await settle();
+    mockClient = makeClient();
+    await new Promise((r) => setTimeout(r, 100));
+    await settle();
+
+    expect(patches).toHaveLength(1);
+  });
+
+  test("retries stop once the backoff schedule is exhausted", async () => {
+    const queue = makeQueue({ retryDelaysMs: [50, 50] });
+    respond = () => new Response("nope", { status: 500 });
+    queue.enqueue("a");
+    await settle();
+    await new Promise((r) => setTimeout(r, 50));
+    await settle();
+    await new Promise((r) => setTimeout(r, 50));
+    await settle();
+    expect(patches).toHaveLength(3);
+
+    await new Promise((r) => setTimeout(r, 100));
+    await settle();
+    expect(patches).toHaveLength(3);
+  });
+
+  test("a new enqueue during backoff supersedes the retry and resets the bound", async () => {
+    const queue = makeQueue({ retryDelaysMs: [100] });
+    respond = () => new Response("nope", { status: 500 });
+    queue.enqueue("a");
+    await settle();
+    queue.enqueue("b");
+    await settle();
+    expect(patches.map((p) => p.body.value)).toEqual(["a", "b"]);
+
+    await new Promise((r) => setTimeout(r, 100));
+    await settle();
+    expect(patches.map((p) => p.body.value)).toEqual(["a", "b", "b"]);
+
+    await new Promise((r) => setTimeout(r, 100));
+    await settle();
+    expect(patches).toHaveLength(3);
+  });
+
+  test("dispose cancels a pending retry", async () => {
+    const queue = makeQueue({ retryDelaysMs: [300] });
+    respond = () => new Response("nope", { status: 500 });
+    queue.enqueue("a");
+    await settle();
+    queue.dispose();
+    await new Promise((r) => setTimeout(r, 300));
+    await settle();
+
+    expect(patches).toHaveLength(1);
+  });
+
+  test("without maxAgeMs a matching key never expires", async () => {
+    const queue = makeQueue({
+      loadSyncedKey: () => ({
+        key: "https://platform.a|asst-1|a",
+        syncedAt: 0,
+      }),
+    });
+    queue.enqueue("a");
+    await settle();
+
+    expect(patches).toHaveLength(0);
+  });
+});

package/src/platform/platform-patch-queue.ts

@@ -0,0 +1,190 @@
+/**
+ * Serialized, deduplicated PATCH queue for the platform Assistant record.
+ *
+ * Each `enqueue` bumps a sequence number and chains onto the previous request,
+ * so rapid changes collapse into one PATCH carrying the newest payload and a
+ * stale in-flight response cannot overwrite a newer value. The dedup key is
+ * scoped to the platform destination (base URL + assistant id), so
+ * re-registering elsewhere re-sends an unchanged payload. With `maxAgeMs`, a
+ * key only dedups while its last success is younger than that, and an unref'd
+ * timer re-enqueues the last input at expiry so an idle long-lived process
+ * re-sends without any caller. Best-effort: failures are logged, never
+ * thrown, and leave the dedup key untouched; a failed request re-enqueues
+ * itself on a bounded backoff (superseded by any new enqueue).
+ */
+
+import type { getLogger } from "../util/logger.js";
+import { VellumPlatformClient } from "./client.js";
+
+type Logger = ReturnType<typeof getLogger>;
+
+type PatchBody = Record<string, unknown>;
+
+export interface PatchPayload {
+  /** Identifies the payload content; equal keys are not re-sent. */
+  key: string;
+  /** A function runs only after the key passes dedup; undefined skips. */
+  body: PatchBody | (() => Promise<PatchBody | undefined>);
+}
+
+export interface SyncedKey {
+  /** Destination-scoped dedup key of the last successful PATCH. */
+  key: string;
+  /** Epoch ms of that PATCH. */
+  syncedAt: number;
+}
+
+export interface PlatformPatchQueueOptions<T> {
+  log: Logger;
+  /** Names the synced thing in log lines, e.g. "avatar". */
+  label: string;
+  /** Returns undefined to skip the PATCH entirely. */
+  buildPayload: (
+    input: T,
+  ) => Promise<PatchPayload | undefined> | PatchPayload | undefined;
+  /** Seeds the dedup key on first use (e.g. from disk). */
+  loadSyncedKey?: () => SyncedKey | null;
+  /** Called after each successful PATCH. */
+  saveSyncedKey?: (synced: SyncedKey) => void;
+  /** A matching key older than this re-sends, via a timer; omit to never expire. */
+  maxAgeMs?: number;
+  /** Backoff after each failed attempt; retries stop once exhausted. */
+  retryDelaysMs?: number[];
+}
+
+const DEFAULT_RETRY_DELAYS_MS = [30_000, 120_000, 600_000];
+
+export interface PlatformPatchQueue<T> {
+  enqueue: (input: T) => void;
+  /** Cancels the expiry and retry timers; queued requests still run. */
+  dispose: () => void;
+}
+
+export function createPlatformPatchQueue<T = void>(
+  options: PlatformPatchQueueOptions<T>,
+): PlatformPatchQueue<T> {
+  const {
+    log,
+    label,
+    buildPayload,
+    loadSyncedKey,
+    saveSyncedKey,
+    maxAgeMs,
+    retryDelaysMs = DEFAULT_RETRY_DELAYS_MS,
+  } = options;
+  let lastSynced: SyncedKey | null | undefined;
+  let seq = 0;
+  let pending: Promise<void> = Promise.resolve();
+  let expiryTimer: ReturnType<typeof setTimeout> | undefined;
+  let retryTimer: ReturnType<typeof setTimeout> | undefined;
+
+  function armExpiry(input: T): void {
+    if (maxAgeMs === undefined || !lastSynced) {
+      return;
+    }
+    clearTimeout(expiryTimer);
+    const delay = Math.max(0, lastSynced.syncedAt + maxAgeMs - Date.now());
+    expiryTimer = setTimeout(() => enqueue(input), delay);
+    expiryTimer.unref?.();
+  }
+
+  function armRetry(input: T, requestSeq: number, attempt: number): void {
+    const delay = retryDelaysMs[attempt];
+    if (requestSeq !== seq || delay === undefined) {
+      return;
+    }
+    clearTimeout(retryTimer);
+    retryTimer = setTimeout(() => schedule(input, attempt + 1), delay);
+    retryTimer.unref?.();
+  }
+
+  async function run(
+    input: T,
+    requestSeq: number,
+    attempt: number,
+  ): Promise<void> {
+    try {
+      if (requestSeq !== seq) {
+        return;
+      }
+      const client = await VellumPlatformClient.create();
+      const assistantId = client?.platformAssistantId;
+      if (!client || !assistantId) {
+        return;
+      }
+
+      const payload = await buildPayload(input);
+      if (!payload || requestSeq !== seq) {
+        return;
+      }
+      const key = `${client.baseUrl}|${assistantId}|${payload.key}`;
+      lastSynced ??= loadSyncedKey?.() ?? null;
+      if (
+        lastSynced?.key === key &&
+        (maxAgeMs === undefined || Date.now() - lastSynced.syncedAt < maxAgeMs)
+      ) {
+        armExpiry(input);
+        return;
+      }
+      const body =
+        typeof payload.body === "function"
+          ? await payload.body()
+          : payload.body;
+      if (!body || requestSeq !== seq) {
+        return;
+      }
+
+      const resp = await client.fetch(
+        `/v1/assistants/${encodeURIComponent(assistantId)}/`,
+        {
+          method: "PATCH",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(15_000),
+        },
+      );
+
+      if (resp.ok) {
+        lastSynced = { key, syncedAt: Date.now() };
+        saveSyncedKey?.(lastSynced);
+        armExpiry(input);
+        log.info(
+          { key: payload.key, assistantId },
+          `Synced ${label} to platform`,
+        );
+      } else {
+        log.warn(
+          {
+            status: resp.status,
+            body: await resp.text(),
+            assistantId,
+            attempt,
+          },
+          `Failed to sync ${label} to platform`,
+        );
+        armRetry(input, requestSeq, attempt);
+      }
+    } catch (err) {
+      log.warn({ err, attempt }, `Error syncing ${label} to platform`);
+      armRetry(input, requestSeq, attempt);
+    }
+  }
+
+  function schedule(input: T, attempt: number): void {
+    const mySeq = ++seq;
+    pending = pending.then(() => run(input, mySeq, attempt)).catch(() => {});
+  }
+
+  function enqueue(input: T): void {
+    clearTimeout(retryTimer);
+    schedule(input, 0);
+  }
+
+  return {
+    enqueue,
+    dispose(): void {
+      clearTimeout(expiryTimer);
+      clearTimeout(retryTimer);
+    },
+  };
+}