@vellumai/assistant 0.8.1 → 0.8.3

package/src/runtime/routes/channel-availability-routes.ts

@@ -0,0 +1,126 @@
+/**
+ * Route handler for channel availability.
+ *
+ * GET /v1/channels/available — return the channels this assistant can
+ * surface to clients (Contacts / GuardianChannels views, etc.) along with
+ * their display metadata (label, subtitle, icon, verification capability,
+ * setup-message copy). Today this is a fixed base list plus `email` when
+ * an inbox is registered; eventually the list will be driven by
+ * plugins/skills the assistant has loaded. Clients should treat the
+ * response as authoritative and stop carrying their own per-channel
+ * switches.
+ *
+ * Distinct from `/v1/channels/readiness` (which answers "is this channel
+ * configured and working?"). Availability answers "could this channel be
+ * surfaced for setup/verification at all?".
+ */
+
+import { z } from "zod";
+
+import { isA2AEnabled } from "../../a2a/feature-gate.js";
+import {
+  CHANNEL_IDS,
+  CHANNEL_METADATA,
+  type ChannelId,
+  type ChannelInfo,
+} from "../../channels/types.js";
+import { getConfig } from "../../config/loader.js";
+import { VellumPlatformClient } from "../../platform/client.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+// Base list every assistant currently surfaces. Order is the display
+// order clients should render. Keep stable — clients sort by index.
+const BASE_AVAILABLE_CHANNELS: readonly ChannelId[] = [
+  "slack",
+  "telegram",
+  "phone",
+] as const;
+
+interface EmailAddressListResponse {
+  count?: number;
+  results?: Array<{ id: string; address: string }>;
+}
+
+/**
+ * Best-effort check that an inbox address is registered for this
+ * assistant. A platform fetch failure is treated as "no inbox" — we
+ * prefer to under-report than block the entire Contacts page when the
+ * platform is briefly unreachable.
+ */
+async function hasRegisteredInbox(): Promise<boolean> {
+  const client = await VellumPlatformClient.create();
+  if (!client?.platformAssistantId) {
+    return false;
+  }
+
+  try {
+    const response = await client.fetch(
+      `/v1/assistants/${client.platformAssistantId}/email-addresses/`,
+    );
+    if (!response.ok) {
+      return false;
+    }
+    const data = (await response.json()) as EmailAddressListResponse;
+    if (typeof data.count === "number") {
+      return data.count > 0;
+    }
+    return Array.isArray(data.results) && data.results.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function handleGetChannelAvailability(
+  _args: RouteHandlerArgs,
+): Promise<{ channels: ChannelInfo[] }> {
+  const ids: ChannelId[] = [...BASE_AVAILABLE_CHANNELS];
+  if (await hasRegisteredInbox()) {
+    ids.push("email");
+  }
+  if (isA2AEnabled(getConfig())) {
+    ids.push("a2a");
+  }
+  // CHANNEL_METADATA is `Partial<Record<ChannelId, ChannelInfo>>` because
+  // unsurfaced channels deliberately have no metadata. `ids` only ever
+  // contains channels that BASE_AVAILABLE_CHANNELS / the email branch
+  // explicitly chose, so the lookup is always defined — filter to satisfy
+  // the type system without a non-null assertion.
+  const channels = ids
+    .map((id) => CHANNEL_METADATA[id])
+    .filter((info): info is ChannelInfo => info !== undefined);
+  return { channels };
+}
+
+const channelInfoSchema = z.object({
+  id: z.enum(CHANNEL_IDS),
+  label: z.string(),
+  subtitle: z.string(),
+  icon: z.string(),
+  supportsVerification: z.boolean(),
+  setupMessages: z.object({
+    guardian: z.string(),
+    contact: z.string(),
+  }),
+});
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "channels_available_get",
+    endpoint: "channels/available",
+    method: "GET",
+    summary: "Get available channels",
+    description:
+      "Return the channels this assistant can surface to clients, with " +
+      "display metadata (label, icon, verification capability, setup " +
+      "copy). Today this is a fixed base list plus `email` when an inbox " +
+      "is registered; will become plugin/skill-driven in future.",
+    tags: ["channels"],
+    requirePolicyEnforcement: true,
+    handler: handleGetChannelAvailability,
+    responseBody: z.object({
+      channels: z
+        .array(channelInfoSchema)
+        .describe("Available channels in display order"),
+    }),
+  },
+];

package/src/runtime/routes/consolidation-routes.ts

@@ -17,11 +17,16 @@ import { z } from "zod";
 
 import { getConfig } from "../../config/loader.js";
 import { getMemoryCheckpoint } from "../../memory/checkpoints.js";
+import {
+  getMessageRoleStatsByConversation,
+  listConversationsBySource,
+} from "../../memory/conversation-queries.js";
 import {
   enqueueMemoryJob,
   hasActiveJobOfType,
 } from "../../memory/jobs-store.js";
 import { GRAPH_MAINTENANCE_CHECKPOINTS } from "../../memory/jobs-worker.js";
+import { MEMORY_V2_CONSOLIDATION_SOURCE } from "../../memory/v2/constants.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -111,4 +116,99 @@ export const ROUTES: RouteDefinition[] = [
       return { success: true, ran: true, jobId };
     },
   },
+  {
+    operationId: "listConsolidationRuns",
+    endpoint: "consolidation/runs",
+    method: "GET",
+    policyKey: "consolidation",
+    summary: "List consolidation runs",
+    description:
+      "Return recent memory v2 consolidation conversations as run records. " +
+      "Each consolidation dispatch creates exactly one background conversation " +
+      "tagged with `source = memory_v2_consolidation`; that conversation IS " +
+      "the run. Synthetic fields: `id` mirrors `conversationId` (no separate " +
+      "run row exists), `scheduledFor` and `startedAt` both equal " +
+      "`conversation.createdAt` (no separate schedule timestamp), " +
+      "`finishedAt` is the `createdAt` of the latest assistant message in " +
+      "the conversation (NOT `conversation.lastMessageAt`, which the kickoff " +
+      "user prompt bumps before the agent runs). `status` is `'ok'` when " +
+      "the conversation has at least one assistant message — i.e. positive " +
+      "evidence the agent emitted output — otherwise `'running'`. This is a " +
+      "weaker signal than heartbeat's `'ok'`: without a dedicated runs " +
+      "table we cannot distinguish 'ran cleanly' from 'crashed after " +
+      "emitting at least one assistant message'. `skipReason` and `error` " +
+      "are always null — skipped runs (lock held, disabled, empty buffer) " +
+      "never create a conversation, and run failure detail is not stored " +
+      "on the conversation row. Shape mirrors `heartbeat/runs` so the " +
+      "schedules settings UI can reuse its run-row component.",
+    tags: ["consolidation"],
+    queryParams: [
+      {
+        name: "limit",
+        schema: { type: "integer" },
+        description: "Max runs to return (default 20, max 100)",
+      },
+    ],
+    responseBody: z.object({
+      runs: z
+        .array(
+          z.object({
+            id: z.string(),
+            scheduledFor: z.number(),
+            startedAt: z.number().nullable(),
+            finishedAt: z.number().nullable(),
+            durationMs: z.number().nullable(),
+            status: z.enum(["ok", "running"]),
+            skipReason: z.string().nullable(),
+            error: z.string().nullable(),
+            conversationId: z.string().nullable(),
+            createdAt: z.number(),
+          }),
+        )
+        .describe("Consolidation run records"),
+    }),
+    handler: async ({ queryParams }: RouteHandlerArgs) => {
+      const params = queryParams ?? {};
+      const rawLimit = Number(params.limit ?? 20);
+      const limit = Number.isFinite(rawLimit)
+        ? Math.min(Math.max(Math.floor(rawLimit), 1), 100)
+        : 20;
+      const rows = listConversationsBySource(
+        MEMORY_V2_CONSOLIDATION_SOURCE,
+        limit,
+      );
+      // Aggregate assistant-message stats in one batched query: presence of
+      // an assistant message is the strongest "agent emitted output" signal
+      // available without a dedicated consolidation runs table. The kickoff
+      // user prompt is persisted via `addMessage` before the agent run,
+      // which bumps `conversations.lastMessageAt` — so that field cannot
+      // be used to infer completion.
+      const assistantStats = getMessageRoleStatsByConversation(
+        rows.map((r) => r.id),
+        "assistant",
+      );
+      return {
+        runs: rows.map((c) => {
+          const stat = assistantStats.get(c.id);
+          const hasAssistantOutput = (stat?.count ?? 0) > 0;
+          const finishedAt = hasAssistantOutput ? stat!.lastAt : null;
+          return {
+            id: c.id,
+            scheduledFor: c.createdAt,
+            startedAt: c.createdAt,
+            finishedAt,
+            durationMs:
+              finishedAt != null ? finishedAt - c.createdAt : null,
+            status: (hasAssistantOutput ? "ok" : "running") as
+              | "ok"
+              | "running",
+            skipReason: null,
+            error: null,
+            conversationId: c.id,
+            createdAt: c.createdAt,
+          };
+        }),
+      };
+    },
+  },
 ];

package/src/runtime/routes/conversation-cli-routes.ts

@@ -6,15 +6,18 @@
  * used by the macOS / web clients.
  */
 
+import { v4 as uuid } from "uuid";
 import { z } from "zod";
 
 import { clearAllConversations as clearAllActive } from "../../daemon/handlers/conversations.js";
 import { formatJson, formatMarkdown } from "../../export/formatter.js";
 import {
+  addMessage,
   createConversation,
   getConversation,
   getMessages,
 } from "../../memory/conversation-crud.js";
+import { setConversationKey } from "../../memory/conversation-key-store.js";
 import { listConversations } from "../../memory/conversation-queries.js";
 import { getLogger } from "../../util/logger.js";
 import { BadRequestError, NotFoundError } from "./errors.js";
@@ -45,12 +48,43 @@ function handleListCli({ body = {} }: RouteHandlerArgs) {
 // create (CLI)
 // ---------------------------------------------------------------------------
 
-function handleCreateCli({ body = {} }: RouteHandlerArgs) {
+const seededConversationMessageSchema = z.object({
+  role: z.enum(["user", "assistant"]),
+  content: z.string(),
+});
+
+type SeededConversationMessage = z.infer<
+  typeof seededConversationMessageSchema
+>;
+
+function textContentJson(text: string): string {
+  return JSON.stringify([{ type: "text", text }]);
+}
+
+async function handleCreateCli({ body = {} }: RouteHandlerArgs) {
   const title = body.title as string | undefined;
+  const messages =
+    (body.messages as SeededConversationMessage[] | undefined) ?? [];
+
   const conversation = createConversation(title);
+  const conversationKey = uuid();
+  setConversationKey(conversationKey, conversation.id);
+
+  for (const message of messages) {
+    await addMessage(
+      conversation.id,
+      message.role,
+      textContentJson(message.content),
+      undefined,
+      { skipIndexing: true },
+    );
+  }
+
   return {
     id: conversation.id,
     title: conversation.title ?? "New Conversation",
+    conversationKey,
+    messagesInserted: messages.length,
   };
 }
 
@@ -109,7 +143,10 @@ function handleExportCli({ body = {} }: RouteHandlerArgs) {
 async function handleClearCli(_args: RouteHandlerArgs) {
   // Tear down in-memory conversation state before DB clear.
   const cleared = clearAllActive();
-  log.info({ cleared }, "CLI conversations clear: active conversations torn down");
+  log.info(
+    { cleared },
+    "CLI conversations clear: active conversations torn down",
+  );
   return { cleared };
 }
 
@@ -146,14 +183,18 @@ export const ROUTES: RouteDefinition[] = [
     endpoint: "conversations/cli/create",
     method: "POST",
     summary: "Create a conversation (CLI)",
-    description: "Create a new conversation with an optional title.",
+    description:
+      "Create a new conversation with an optional title and seeded messages.",
     tags: ["conversations"],
     requestBody: z.object({
       title: z.string().optional(),
+      messages: z.array(seededConversationMessageSchema).optional(),
     }),
     responseBody: z.object({
       id: z.string(),
       title: z.string(),
+      conversationKey: z.string(),
+      messagesInserted: z.number().int().nonnegative(),
     }),
     handler: handleCreateCli,
   },

package/src/runtime/routes/conversation-list-routes.ts

@@ -28,12 +28,11 @@ import { getBindingsForConversations } from "../../memory/external-conversation-
 import { listGroups } from "../../memory/group-crud.js";
 import { UserError } from "../../util/errors.js";
 import { getLogger } from "../../util/logger.js";
-import { buildAssistantEvent } from "../assistant-event.js";
-import { assistantEventHub } from "../assistant-event-hub.js";
 import {
   buildConversationDetailResponse,
   serializeConversationSummary,
 } from "../services/conversation-serializer.js";
+import { publishConversationListAndMetadataChanged } from "../sync/resource-sync-events.js";
 import {
   BadRequestError,
   InternalError,
@@ -54,22 +53,6 @@ function resolveOrThrow(rawId: string): string {
   return id;
 }
 
-function publishListInvalidated(): void {
-  assistantEventHub
-    .publish(
-      buildAssistantEvent({
-        type: "conversation_list_invalidated",
-        reason: "seen_changed",
-      }),
-    )
-    .catch((err) => {
-      log.warn(
-        { err },
-        "Failed to publish conversation_list_invalidated (seen_changed)",
-      );
-    });
-}
-
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
@@ -159,7 +142,7 @@ function handleRecordSeen({ body = {} }: RouteHandlerArgs) {
     });
 
     if (wasUnseen) {
-      publishListInvalidated();
+      publishConversationListAndMetadataChanged("seen_changed", conversationId);
     }
 
     return { ok: true };
@@ -179,7 +162,7 @@ function handleMarkUnread({ body = {} }: RouteHandlerArgs) {
   try {
     const changed = markConversationUnread(conversationId);
     if (changed) {
-      publishListInvalidated();
+      publishConversationListAndMetadataChanged("seen_changed", conversationId);
     }
     return { ok: true };
   } catch (err) {

package/src/runtime/routes/conversation-management-routes.ts

@@ -27,7 +27,6 @@ import {
   switchConversation,
   undoLastMessage,
 } from "../../daemon/handlers/conversations.js";
-import type { ConversationListInvalidatedReason } from "../../daemon/message-types/conversations.js";
 import { normalizeConversationType } from "../../daemon/message-types/shared.js";
 import {
   archiveConversation,
@@ -49,9 +48,12 @@ import { enqueueMemoryJob } from "../../memory/jobs-store.js";
 import { deleteSchedule } from "../../schedule/schedule-store.js";
 import { UserError } from "../../util/errors.js";
 import { getLogger } from "../../util/logger.js";
-import { buildAssistantEvent } from "../assistant-event.js";
-import { assistantEventHub } from "../assistant-event-hub.js";
 import { buildConversationDetailResponse } from "../services/conversation-serializer.js";
+import {
+  publishConversationListAndMetadataChanged,
+  publishConversationListChanged,
+  publishConversationTitleChanged,
+} from "../sync/resource-sync-events.js";
 import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
 import { setInferenceProfileSession } from "./inference-profile-session-handler.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -68,24 +70,6 @@ function resolveOrThrow(rawId: string): string {
   return id;
 }
 
-function publishListInvalidated(
-  reason: ConversationListInvalidatedReason,
-): void {
-  assistantEventHub
-    .publish(
-      buildAssistantEvent({
-        type: "conversation_list_invalidated",
-        reason,
-      }),
-    )
-    .catch((err) => {
-      log.warn(
-        { err },
-        `Failed to publish conversation_list_invalidated (${reason})`,
-      );
-    });
-}
-
 function cancelScheduleIfLast(conversationId: string): void {
   const conv = getConversation(conversationId);
   if (
@@ -108,6 +92,7 @@ function handleCreateConversation({ body = {} }: RouteHandlerArgs) {
   });
   if (result.created) {
     updateConversationTitle(result.conversationId, "New Conversation");
+    publishConversationListAndMetadataChanged("created", result.conversationId);
   }
   log.info(
     {
@@ -151,6 +136,7 @@ async function handleForkConversation({ body = {} }: RouteHandlerArgs) {
         `Forked conversation ${forkedConversation.id} could not be loaded`,
       );
     }
+    publishConversationListAndMetadataChanged("created", forkedConversation.id);
     return { conversation: detail.conversation };
   } catch (err) {
     if (err instanceof UserError) {
@@ -217,25 +203,7 @@ function handleRenameConversation({
   }
   updateConversationTitle(pathParams.id!, name, 0);
 
-  assistantEventHub
-    .publish(
-      buildAssistantEvent(
-        {
-          type: "conversation_title_updated",
-          conversationId: pathParams.id!,
-          title: name,
-        },
-        pathParams.id!,
-      ),
-    )
-    .catch((err) => {
-      log.warn(
-        { err, conversationId: pathParams.id },
-        "Failed to publish conversation_title_updated",
-      );
-    });
-
-  publishListInvalidated("renamed");
+  publishConversationTitleChanged(pathParams.id!, name);
 
   return { ok: true };
 }
@@ -249,6 +217,7 @@ function handleClearAllConversations({ headers = {} }: RouteHandlerArgs) {
     );
   }
   clearAllConversations();
+  publishConversationListChanged("deleted");
   return undefined;
 }
 
@@ -279,6 +248,7 @@ function handleWipeConversation({ pathParams = {} }: RouteHandlerArgs) {
     },
     "Wiped conversation and reverted memory changes",
   );
+  publishConversationListAndMetadataChanged("deleted", resolvedId);
   return {
     wiped: true,
     unsupersededItems: 0,
@@ -308,7 +278,7 @@ function handleDeleteConversation({ pathParams = {} }: RouteHandlerArgs) {
   }
   log.info({ conversationId: resolvedId }, "Deleted conversation");
 
-  publishListInvalidated("deleted");
+  publishConversationListAndMetadataChanged("deleted", resolvedId);
 
   return undefined;
 }
@@ -319,6 +289,7 @@ function handleArchiveConversation({ pathParams = {} }: RouteHandlerArgs) {
   if (!archived) {
     throw new NotFoundError(`Conversation ${pathParams.id} not found`);
   }
+  publishConversationListAndMetadataChanged("reordered", resolvedId);
   return { ok: true, conversationId: resolvedId };
 }
 
@@ -328,6 +299,7 @@ function handleUnarchiveConversation({ pathParams = {} }: RouteHandlerArgs) {
   if (!unarchived) {
     throw new NotFoundError(`Conversation ${pathParams.id} not found`);
   }
+  publishConversationListAndMetadataChanged("reordered", resolvedId);
   return { ok: true, conversationId: resolvedId };
 }
 
@@ -387,7 +359,10 @@ function handleReorderConversations({ body = {} }: RouteHandlerArgs) {
       groupId: u.groupId,
     })),
   );
-  publishListInvalidated("reordered");
+  publishConversationListAndMetadataChanged(
+    "reordered",
+    updates.map((u) => u.conversationId),
+  );
   return { ok: true };
 }