@vellumai/assistant 0.8.6 → 0.8.7-dev.202606052118.34cd356

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

@@ -15,25 +15,39 @@
 
 import { z } from "zod";
 
-import { getConfig } from "../../config/loader.js";
+import {
+  getConfig,
+  invalidateConfigCache,
+  loadRawConfig,
+  saveRawConfig,
+} from "../../config/loader.js";
+import type { AssistantConfig } from "../../config/schema.js";
 import { getMemoryCheckpoint } from "../../memory/checkpoints.js";
 import {
   getMessageRoleStatsByConversation,
   listConversationsBySource,
 } from "../../memory/conversation-queries.js";
 import {
+  cancelPendingAutomaticConsolidationJobs,
   enqueueMemoryJob,
   hasActiveJobOfType,
+  MEMORY_V2_CONSOLIDATION_JOB_TRIGGERS,
 } from "../../memory/jobs-store.js";
 import { GRAPH_MAINTENANCE_CHECKPOINTS } from "../../memory/jobs-worker.js";
+import { getUsageCostForConversationWindow } from "../../memory/llm-usage-store.js";
 import { MEMORY_V2_CONSOLIDATION_SOURCE } from "../../memory/v2/constants.js";
-import { BadRequestError } from "./errors.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import { BadRequestError, InternalError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 function isConsolidationAvailable(): boolean {
   return getConfig().memory.v2.enabled;
 }
 
+function isAutomaticConsolidationEnabled(config: AssistantConfig): boolean {
+  return config.memory.v2.enabled && config.memory.v2.consolidation_enabled;
+}
+
 function consolidationIntervalMs(): number {
   return getConfig().memory.v2.consolidation_interval_hours * 60 * 60 * 1000;
 }
@@ -47,6 +61,61 @@ function readLastRunAt(): number | null {
   return Number.isFinite(parsed) ? parsed : null;
 }
 
+function readConsolidationConfigResponse() {
+  const config = getConfig();
+  const available = config.memory.v2.enabled;
+  const enabled = isAutomaticConsolidationEnabled(config);
+  const intervalMs = consolidationIntervalMs();
+  const lastRunAt = readLastRunAt();
+  const nextRunAt =
+    enabled && lastRunAt != null ? lastRunAt + intervalMs : null;
+  return {
+    available,
+    enabled,
+    intervalMs,
+    nextRunAt,
+    lastRunAt,
+    success: true,
+  };
+}
+
+function handleUpdateConfig(body: Record<string, unknown>) {
+  const consolidationPatch: Record<string, unknown> = {};
+  const disablingAutomaticConsolidation = body.enabled === false;
+  if ("enabled" in body && typeof body.enabled === "boolean") {
+    consolidationPatch.consolidation_enabled = body.enabled;
+  }
+
+  try {
+    const raw = loadRawConfig() as Record<string, unknown>;
+    const memory =
+      raw.memory != null && typeof raw.memory === "object"
+        ? (raw.memory as Record<string, unknown>)
+        : {};
+    const v2 =
+      memory.v2 != null && typeof memory.v2 === "object"
+        ? (memory.v2 as Record<string, unknown>)
+        : {};
+
+    raw.memory = {
+      ...memory,
+      v2: {
+        ...v2,
+        ...consolidationPatch,
+      },
+    };
+    saveRawConfig(raw);
+    invalidateConfigCache();
+    if (disablingAutomaticConsolidation) {
+      cancelPendingAutomaticConsolidationJobs();
+    }
+  } catch {
+    throw new InternalError("Failed to save consolidation config");
+  }
+
+  return readConsolidationConfigResponse();
+}
+
 // ---------------------------------------------------------------------------
 // Shared ROUTES
 // ---------------------------------------------------------------------------
@@ -56,8 +125,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "getConsolidationConfig",
     endpoint: "consolidation/config",
     method: "GET",
-    policyKey: "consolidation",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get consolidation config",
     description:
       "Return the current memory v2 consolidation schedule configuration.",
@@ -71,26 +142,46 @@ export const ROUTES: RouteDefinition[] = [
       success: z.boolean(),
     }),
     handler: async (_args: RouteHandlerArgs) => {
-      const enabled = getConfig().memory.v2.enabled;
-      const intervalMs = consolidationIntervalMs();
-      const lastRunAt = readLastRunAt();
-      const nextRunAt = lastRunAt != null ? lastRunAt + intervalMs : null;
-      return {
-        available: enabled,
-        enabled,
-        intervalMs,
-        nextRunAt,
-        lastRunAt,
-        success: true,
-      };
+      return readConsolidationConfigResponse();
+    },
+  },
+  {
+    operationId: "updateConsolidationConfig",
+    endpoint: "consolidation/config",
+    method: "PUT",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Update consolidation config",
+    description: "Update the memory v2 consolidation schedule configuration.",
+    tags: ["consolidation"],
+    requestBody: z.object({
+      enabled: z
+        .boolean()
+        .optional()
+        .describe("Enable or disable automatic consolidation"),
+    }),
+    responseBody: z.object({
+      available: z.boolean(),
+      enabled: z.boolean(),
+      intervalMs: z.number(),
+      nextRunAt: z.number().nullable(),
+      lastRunAt: z.number().nullable(),
+      success: z.boolean(),
+    }),
+    handler: async ({ body = {} }: RouteHandlerArgs) => {
+      return handleUpdateConfig(body);
     },
   },
   {
     operationId: "runConsolidationNow",
     endpoint: "consolidation/run-now",
     method: "POST",
-    policyKey: "consolidation",
-    requirePolicyEnforcement: true,
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Run consolidation now",
     description:
       "Enqueue an immediate memory v2 consolidation job. Returns once the job is queued; the job itself runs through the memory jobs worker.",
@@ -112,7 +203,9 @@ export const ROUTES: RouteDefinition[] = [
       if (hasActiveJobOfType("memory_v2_consolidate")) {
         return { success: true, ran: false, jobId: null };
       }
-      const jobId = enqueueMemoryJob("memory_v2_consolidate", {});
+      const jobId = enqueueMemoryJob("memory_v2_consolidate", {
+        trigger: MEMORY_V2_CONSOLIDATION_JOB_TRIGGERS.manual,
+      });
       return { success: true, ran: true, jobId };
     },
   },
@@ -120,7 +213,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "listConsolidationRuns",
     endpoint: "consolidation/runs",
     method: "GET",
-    policyKey: "consolidation",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "List consolidation runs",
     description:
       "Return recent memory v2 consolidation conversations as run records. " +
@@ -162,6 +258,9 @@ export const ROUTES: RouteDefinition[] = [
             skipReason: z.string().nullable(),
             error: z.string().nullable(),
             conversationId: z.string().nullable(),
+            conversationExists: z.boolean(),
+            conversationArchivedAt: z.number().nullable(),
+            estimatedCostUsd: z.number(),
             createdAt: z.number(),
           }),
         )
@@ -187,24 +286,33 @@ export const ROUTES: RouteDefinition[] = [
         rows.map((r) => r.id),
         "assistant",
       );
+      const now = Date.now();
       return {
         runs: rows.map((c) => {
           const stat = assistantStats.get(c.id);
           const hasAssistantOutput = (stat?.count ?? 0) > 0;
           const finishedAt = hasAssistantOutput ? stat!.lastAt : null;
+          const estimatedCostUsd =
+            c.totalEstimatedCost > 0
+              ? c.totalEstimatedCost
+              : getUsageCostForConversationWindow({
+                  conversationId: c.id,
+                  from: c.createdAt,
+                  to: finishedAt ?? now,
+                });
           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",
+            durationMs: finishedAt != null ? finishedAt - c.createdAt : null,
+            status: (hasAssistantOutput ? "ok" : "running") as "ok" | "running",
             skipReason: null,
             error: null,
             conversationId: c.id,
+            conversationExists: true,
+            conversationArchivedAt: c.archivedAt,
+            estimatedCostUsd,
             createdAt: c.createdAt,
           };
         }),

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

@@ -20,6 +20,7 @@ import { z } from "zod";
 
 import { getLogger } from "../../util/logger.js";
 import { broadcastMessage } from "../assistant-event-hub.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("contact-prompt-routes");
@@ -155,6 +156,10 @@ export const CONTACT_PROMPT_ROUTES: RouteDefinition[] = [
     operationId: "contacts_prompt",
     endpoint: "contacts/prompt",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleContactPrompt,
     summary: "Prompt user to register a contact channel",
     description:
@@ -174,6 +179,10 @@ export const CONTACT_PROMPT_ROUTES: RouteDefinition[] = [
     operationId: "resolve_contact_prompt",
     endpoint: "resolve_contact_prompt",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: resolveContactPrompt,
     summary: "Gateway callback: resolve a pending contact prompt",
     description:

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

@@ -26,6 +26,7 @@ import type {
   ContactType,
 } from "../../contacts/types.js";
 import { resolveGuardianName } from "../../prompts/user-reference.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import {
   createIngressInvite,
   listIngressInvites,
@@ -34,11 +35,7 @@ import {
   revokeIngressInvite,
   triggerInviteCall,
 } from "../invite-service.js";
-import {
-  BadRequestError,
-  ConflictError,
-  NotFoundError,
-} from "./errors.js";
+import { BadRequestError, ConflictError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 function withGuardianNameOverride<
@@ -80,6 +77,39 @@ function isChannelPolicy(value: string): value is ChannelPolicy {
   return (VALID_CHANNEL_POLICIES as readonly string[]).includes(value);
 }
 
+// ---------------------------------------------------------------------------
+// Response schemas (drive OpenAPI spec → codegen → typed SDK)
+// ---------------------------------------------------------------------------
+
+const contactChannelSchema = z.object({
+  id: z.string(),
+  contactId: z.string(),
+  type: z.string(),
+  address: z.string(),
+  isPrimary: z.boolean(),
+  externalUserId: z.string().nullable(),
+  status: z.string(),
+  policy: z.string(),
+  verifiedAt: z.number().nullable(),
+  verifiedVia: z.string().nullable(),
+  lastSeenAt: z.number().nullable(),
+  interactionCount: z.number(),
+  lastInteraction: z.number().nullable(),
+  revokedReason: z.string().nullable(),
+  blockedReason: z.string().nullable(),
+});
+
+const contactSchema = z.object({
+  id: z.string(),
+  displayName: z.string(),
+  role: z.string(),
+  notes: z.string().nullable().optional(),
+  contactType: z.string().nullable().optional(),
+  lastInteraction: z.number().nullable().optional(),
+  interactionCount: z.number(),
+  channels: z.array(contactChannelSchema),
+});
+
 // ---------------------------------------------------------------------------
 // Contact handlers (transport-agnostic)
 // ---------------------------------------------------------------------------
@@ -251,6 +281,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "listContacts",
     endpoint: "contacts",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "List contacts",
     description:
       "Return all contacts, optionally filtered by type or channel status.",
@@ -290,7 +324,7 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({
       ok: z.boolean(),
       contacts: z
-        .array(z.unknown())
+        .array(contactSchema)
         .describe("Contact objects with channels and metadata"),
     }),
     handler: ({ queryParams }: RouteHandlerArgs) =>
@@ -302,6 +336,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "invites_list",
     endpoint: "contacts/invites",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleListInvites,
     summary: "List invites",
     description:
@@ -326,6 +364,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "invites_create",
     endpoint: "contacts/invites",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleCreateInvite,
     responseStatus: "201",
     summary: "Create an invite",
@@ -363,6 +405,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "invites_redeem",
     endpoint: "contacts/invites/redeem",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleRedeemInvite,
     summary: "Redeem an invite",
     description: "Redeem an invite by token or voice code.",
@@ -397,7 +443,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "invites_revoke",
     endpoint: "contacts/invites/:id",
     method: "DELETE",
-    policyKey: "contacts/invites",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleRevokeInvite,
     summary: "Revoke an invite",
     description: "Revoke an invite by ID.",
@@ -412,7 +461,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "invites_trigger_call",
     endpoint: "contacts/invites/:id/call",
     method: "POST",
-    policyKey: "contacts/invites",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleTriggerInviteCall,
     summary: "Trigger invite call",
     description: "Trigger an outbound call for a phone invite.",
@@ -433,6 +485,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "search_contacts",
     endpoint: "contacts/search",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Search contacts",
     description: "Search contacts by query, channel address, or channel type.",
     tags: ["contacts"],
@@ -442,7 +498,7 @@ export const ROUTES: RouteDefinition[] = [
       channelType: z.string().optional(),
       limit: z.number().optional(),
     }),
-    responseBody: z.array(z.object({}).passthrough()),
+    responseBody: z.array(contactSchema),
     handler: ({ body = {} }: RouteHandlerArgs) => {
       const parsed = z
         .object({
@@ -461,17 +517,24 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "getContact",
     endpoint: "contacts/:id",
     method: "GET",
-    policyKey: "contacts",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get a contact",
     description:
       "Return a single contact with its channels and assistant metadata.",
     tags: ["contacts"],
     responseBody: z.object({
       ok: z.boolean(),
-      contact: z.object({}).passthrough().describe("Contact details"),
+      contact: contactSchema,
       assistantMetadata: z
-        .object({})
-        .passthrough()
+        .object({
+          contactId: z.string(),
+          species: z.string(),
+          metadata: z.object({}).passthrough().nullable(),
+        })
+        .optional()
         .describe("Assistant-side metadata"),
     }),
     handler: ({ pathParams }: RouteHandlerArgs) =>
@@ -481,6 +544,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "merge_contacts",
     endpoint: "contacts/merge",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Merge two contacts",
     description: "Merge two contacts, keeping one and absorbing the other.",
     tags: ["contacts"],
@@ -492,7 +559,7 @@ export const ROUTES: RouteDefinition[] = [
     }),
     responseBody: z.object({
       ok: z.boolean(),
-      contact: z.object({}).passthrough().describe("Merged contact"),
+      contact: contactSchema.describe("Merged contact"),
     }),
     handler: (args: RouteHandlerArgs) => handleMergeContactsRoute(args),
   },
@@ -500,20 +567,22 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "updateContactChannel",
     endpoint: "contact-channels/:contactChannelId",
     method: "PATCH",
-    policyKey: "contact-channels",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Update a contact channel",
     description: "Update status, policy, or reason on a contact's channel.",
     tags: ["contacts"],
     requestBody: z.object({
-      status: z.string().describe("Channel status"),
-      policy: z.string().describe("Channel policy"),
-      reason: z.string().describe("Reason for the change"),
+      status: z.string().optional().describe("Channel status"),
+      policy: z.string().optional().describe("Channel policy"),
+      reason: z.string().optional().describe("Reason for the change"),
     }),
     responseBody: z.object({
       ok: z.boolean(),
-      contact: z
-        .object({})
-        .passthrough()
+      contact: contactSchema
+        .optional()
         .describe("Updated contact (if applicable)"),
     }),
     handler: (args: RouteHandlerArgs) => handleUpdateContactChannelRoute(args),
@@ -603,5 +672,3 @@ function handleUpdateContactChannelRoute(args: RouteHandlerArgs) {
       : undefined,
   };
 }
-
-

package/src/runtime/routes/content-source-routes.ts

@@ -13,6 +13,7 @@ import { dirname, join } from "node:path";
 import { z } from "zod";
 
 import { getWorkspaceDir } from "../../util/platform.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 // ---------------------------------------------------------------------------
@@ -70,7 +71,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "content_source_set",
     endpoint: "content-source",
     method: "POST",
-    policyKey: "secrets",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Validate and persist a content source URL",
     requestBody: z.object({ url: z.string() }),
     handler: handleContentSource,

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

@@ -11,6 +11,7 @@
 
 import { z } from "zod";
 
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { analyzeConversation } from "../services/analyze-conversation.js";
 import { buildConversationDetailResponse } from "../services/conversation-serializer.js";
 import { conversationSummarySchema } from "./conversation-list-routes.js";
@@ -58,7 +59,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "analyzeConversation",
     endpoint: "conversations/:id/analyze",
     method: "POST",
-    policyKey: "conversations/analyze",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Analyze a conversation",
     description:
       "Create a new conversation with a structured self-assessment of an existing conversation.",

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

@@ -15,6 +15,7 @@ import {
   getMessageById,
 } from "../../memory/conversation-crud.js";
 import { truncate } from "../../util/truncate.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -128,6 +129,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "conversations_attention_list",
     endpoint: "conversations/attention",
     method: "GET",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: handleListConversationAttention,
     summary: "List conversation attention states",
     description: