@vellumai/assistant 0.8.0 → 0.8.2

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

@@ -0,0 +1,121 @@
+/**
+ * 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 {
+  CHANNEL_IDS,
+  CHANNEL_METADATA,
+  type ChannelId,
+  type ChannelInfo,
+} from "../../channels/types.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");
+  }
+  // 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/channel-verification-routes.ts

@@ -177,8 +177,9 @@ export async function handleCreateVerificationSession({
  */
 function handleGetVerificationStatus({
   queryParams = {},
+  body = {},
 }: RouteHandlerArgs) {
-  const channel = (queryParams.channel as ChannelId | undefined) ?? undefined;
+  const channel = (queryParams.channel ?? (body as Record<string, unknown>).channel) as ChannelId | undefined;
   return getVerificationStatus(channel);
 }
 

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

@@ -18,12 +18,8 @@ import {
   mergeContacts,
   searchContacts,
   updateChannelStatus,
-  upsertAssistantContactMetadata,
-  upsertContact,
-  validateSpeciesMetadata,
 } from "../../contacts/contact-store.js";
 import type {
-  AssistantSpecies,
   ChannelPolicy,
   ChannelStatus,
   ContactRole,
@@ -58,10 +54,6 @@ function withGuardianNameOverride<
 }
 
 const VALID_CONTACT_TYPES: readonly ContactType[] = ["human", "assistant"];
-const VALID_ASSISTANT_SPECIES: readonly AssistantSpecies[] = [
-  "vellum",
-  "openclaw",
-];
 
 const VALID_CHANNEL_STATUSES: readonly ChannelStatus[] = [
   "active",
@@ -80,10 +72,6 @@ function isContactType(value: string): value is ContactType {
   return (VALID_CONTACT_TYPES as readonly string[]).includes(value);
 }
 
-function isAssistantSpecies(value: string): value is AssistantSpecies {
-  return (VALID_ASSISTANT_SPECIES as readonly string[]).includes(value);
-}
-
 function isChannelStatus(value: string): value is ChannelStatus {
   return (VALID_CHANNEL_STATUSES as readonly string[]).includes(value);
 }
@@ -489,34 +477,6 @@ export const ROUTES: RouteDefinition[] = [
     handler: ({ pathParams }: RouteHandlerArgs) =>
       handleGetContact(pathParams!.id),
   },
-  {
-    operationId: "upsert_contact",
-    endpoint: "contacts",
-    method: "POST",
-    summary: "Create or update a contact",
-    description:
-      "Create a new contact or update an existing one. Supports upsert by contactId or channel handle.",
-    tags: ["contacts"],
-    requestBody: z.object({
-      contactId: z.string().describe("Existing contact ID (for update)"),
-      displayName: z.string().describe("Display name"),
-      channels: z
-        .array(z.unknown())
-        .describe("Channel objects with channelId, handle, displayName"),
-      assistantMetadata: z
-        .object({})
-        .passthrough()
-        .describe("Assistant-side metadata"),
-    }),
-    responseBody: z.object({
-      ok: z.boolean(),
-      contact: z
-        .object({})
-        .passthrough()
-        .describe("Created or updated contact"),
-    }),
-    handler: (args: RouteHandlerArgs) => handleUpsertContactRoute(args),
-  },
   {
     operationId: "merge_contacts",
     endpoint: "contacts/merge",
@@ -582,126 +542,6 @@ function handleMergeContactsRoute(args: RouteHandlerArgs) {
   }
 }
 
-function handleUpsertContactRoute(args: RouteHandlerArgs) {
-  const body = (args.body ?? {}) as {
-    id?: string;
-    displayName?: string;
-    notes?: string;
-    role?: string;
-    contactType?: string;
-    assistantMetadata?: {
-      species: string;
-      metadata?: Record<string, unknown>;
-    };
-    channels?: Array<{
-      type: string;
-      address: string;
-      isPrimary?: boolean;
-      status?: string;
-      policy?: string;
-      externalUserId?: string;
-      externalChatId?: string;
-    }>;
-  };
-
-  if (
-    !body.displayName ||
-    typeof body.displayName !== "string" ||
-    body.displayName.trim().length === 0
-  ) {
-    throw new BadRequestError(
-      "displayName is required and must be a non-empty string",
-    );
-  }
-
-  if (body.contactType !== undefined && !isContactType(body.contactType)) {
-    throw new BadRequestError(
-      `Invalid contactType "${body.contactType}". Must be one of: ${VALID_CONTACT_TYPES.join(", ")}`,
-    );
-  }
-
-  if (body.contactType === "assistant") {
-    if (!body.assistantMetadata) {
-      throw new BadRequestError(
-        'assistantMetadata is required when contactType is "assistant"',
-      );
-    }
-    if (!isAssistantSpecies(body.assistantMetadata.species)) {
-      throw new BadRequestError(
-        `Invalid species "${body.assistantMetadata.species}". Must be one of: ${VALID_ASSISTANT_SPECIES.join(", ")}`,
-      );
-    }
-    try {
-      validateSpeciesMetadata(
-        body.assistantMetadata.species as AssistantSpecies,
-        body.assistantMetadata.metadata ?? null,
-      );
-    } catch (err) {
-      throw new BadRequestError(
-        err instanceof Error ? err.message : String(err),
-      );
-    }
-  }
-
-  if (body.contactType === "human" && body.assistantMetadata) {
-    throw new BadRequestError(
-      'assistantMetadata must not be provided when contactType is "human"',
-    );
-  }
-
-  if (body.assistantMetadata && !body.contactType) {
-    throw new BadRequestError(
-      'contactType must be "assistant" when assistantMetadata is provided',
-    );
-  }
-
-  if (body.channels) {
-    if (!Array.isArray(body.channels)) {
-      throw new BadRequestError("channels must be an array");
-    }
-    for (const ch of body.channels) {
-      if (ch.status !== undefined && !isChannelStatus(ch.status)) {
-        throw new BadRequestError(
-          `Invalid channel status "${ch.status}". Must be one of: ${VALID_CHANNEL_STATUSES.join(", ")}`,
-        );
-      }
-      if (ch.policy !== undefined && !isChannelPolicy(ch.policy)) {
-        throw new BadRequestError(
-          `Invalid channel policy "${ch.policy}". Must be one of: ${VALID_CHANNEL_POLICIES.join(", ")}`,
-        );
-      }
-    }
-  }
-
-  try {
-    const contact = upsertContact({
-      id: body.id,
-      displayName: body.displayName.trim(),
-      notes: body.notes,
-      role: body.role as ContactRole | undefined,
-      contactType: body.contactType as ContactType | undefined,
-      channels: body.channels?.map((ch) => ({
-        ...ch,
-        status: ch.status as ChannelStatus | undefined,
-        policy: ch.policy as ChannelPolicy | undefined,
-      })),
-    });
-
-    if (body.assistantMetadata) {
-      upsertAssistantContactMetadata({
-        contactId: contact.id,
-        species: body.assistantMetadata.species as AssistantSpecies,
-        metadata: body.assistantMetadata.metadata ?? null,
-      });
-    }
-
-    return { ok: true, contact: withGuardianNameOverride(contact) };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    throw new BadRequestError(message);
-  }
-}
-
 function handleUpdateContactChannelRoute(args: RouteHandlerArgs) {
   const channelId = args.pathParams!.contactChannelId;
   const body = (args.body ?? {}) as {

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

@@ -0,0 +1,233 @@
+/**
+ * CLI-specific route handlers for conversation operations.
+ *
+ * These routes serve the thin CLI wrappers — they return simple shapes
+ * optimised for terminal output rather than the richer serialisations
+ * 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";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+const log = getLogger("conversation-cli-routes");
+
+// ---------------------------------------------------------------------------
+// list (CLI)
+// ---------------------------------------------------------------------------
+
+function handleListCli({ body = {} }: RouteHandlerArgs) {
+  const limit =
+    body.limit != null ? Number(body.limit) : Number.MAX_SAFE_INTEGER;
+  const includeArchived = (body.includeArchived as boolean) ?? false;
+
+  const rows = listConversations(limit, false, 0, includeArchived);
+  return {
+    conversations: rows.map((c) => ({
+      id: c.id,
+      title: c.title,
+      updatedAt: c.updatedAt,
+    })),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// create (CLI)
+// ---------------------------------------------------------------------------
+
+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,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// export (CLI)
+// ---------------------------------------------------------------------------
+
+function handleExportCli({ body = {} }: RouteHandlerArgs) {
+  const format = (body.format as string) ?? "md";
+  if (format !== "md" && format !== "json") {
+    throw new BadRequestError('format must be "md" or "json"');
+  }
+
+  let conversationId = body.conversationId as string | undefined;
+
+  if (!conversationId) {
+    const all = listConversations(1);
+    if (all.length === 0) {
+      throw new NotFoundError("No conversations found");
+    }
+    conversationId = all[0].id;
+  }
+
+  // Support prefix matching
+  let conversation = getConversation(conversationId);
+  if (!conversation) {
+    const all = listConversations(Number.MAX_SAFE_INTEGER);
+    const match = all.find((c) => c.id.startsWith(conversationId!));
+    if (match) {
+      conversation = match;
+    } else {
+      throw new NotFoundError(`Conversation not found: ${conversationId}`);
+    }
+  }
+
+  const msgs = getMessages(conversation.id);
+  const exportData = {
+    ...conversation,
+    messages: msgs.map((m) => ({
+      role: m.role,
+      content: JSON.parse(m.content),
+      createdAt: m.createdAt,
+    })),
+  };
+
+  const output =
+    format === "json" ? formatJson(exportData) : formatMarkdown(exportData);
+
+  return { output, conversationId: conversation.id };
+}
+
+// ---------------------------------------------------------------------------
+// clear (CLI)
+// ---------------------------------------------------------------------------
+
+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",
+  );
+  return { cleared };
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "conversation_list_cli",
+    endpoint: "conversations/cli/list",
+    method: "POST",
+    summary: "List conversations (CLI)",
+    description:
+      "Simplified conversation list for CLI output — returns id, title, updatedAt.",
+    tags: ["conversations"],
+    requestBody: z.object({
+      limit: z.number().int().positive().optional(),
+      includeArchived: z.boolean().optional(),
+    }),
+    responseBody: z.object({
+      conversations: z.array(
+        z.object({
+          id: z.string(),
+          title: z.string().nullable(),
+          updatedAt: z.number(),
+        }),
+      ),
+    }),
+    handler: handleListCli,
+  },
+  {
+    operationId: "conversation_create_cli",
+    endpoint: "conversations/cli/create",
+    method: "POST",
+    summary: "Create a conversation (CLI)",
+    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,
+  },
+  {
+    operationId: "conversation_export_cli",
+    endpoint: "conversations/cli/export",
+    method: "POST",
+    summary: "Export a conversation (CLI)",
+    description:
+      "Export a conversation as markdown or JSON. Returns the formatted output string.",
+    tags: ["conversations"],
+    requestBody: z.object({
+      conversationId: z.string().optional(),
+      format: z.enum(["md", "json"]).default("md"),
+    }),
+    responseBody: z.object({
+      output: z.string(),
+      conversationId: z.string(),
+    }),
+    handler: handleExportCli,
+  },
+  {
+    operationId: "conversations_clear_cli",
+    endpoint: "conversations/cli/clear",
+    method: "POST",
+    summary: "Clear all conversations (CLI)",
+    description:
+      "Tear down all active conversations and clear the database. " +
+      "The confirmation prompt is handled client-side by the CLI.",
+    tags: ["conversations"],
+    responseBody: z.object({
+      cleared: z.number().int(),
+    }),
+    handler: handleClearCli,
+  },
+];

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) {