@vellumai/assistant 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

package/src/runtime/routes/integrations/slack/share.ts

@@ -5,6 +5,8 @@
  * without going through the legacy Slack share flow.
  */
 
+import { z } from "zod";
+
 import { getApp } from "../../../../memory/app-store.js";
 import {
   listConversations,
@@ -29,12 +31,24 @@ const log = getLogger("slack-share");
 // GET /v1/slack/channels
 // ---------------------------------------------------------------------------
 
-interface NormalizedChannel {
-  id: string;
-  name: string;
-  type: "channel" | "group" | "dm";
-  isPrivate: boolean;
-}
+const NormalizedChannelSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  type: z.enum(["channel", "group", "dm"]),
+  isPrivate: z.boolean(),
+});
+
+type NormalizedChannel = z.infer<typeof NormalizedChannelSchema>;
+
+const SlackChannelsListResultSchema = z.object({
+  channels: z.array(NormalizedChannelSchema),
+});
+
+const SlackShareResultSchema = z.object({
+  ok: z.boolean(),
+  ts: z.string(),
+  channel: z.string(),
+});
 
 function classifyConversation(
   conv: SlackConversation,
@@ -205,6 +219,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "List Slack channels",
     description: "List Slack channels, groups, and DMs for the channel picker.",
     tags: ["integrations"],
+    responseBody: SlackChannelsListResultSchema,
     handler: () => handleListSlackChannels(),
   },
   {
@@ -218,6 +233,12 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Share to Slack channel",
     description: "Post an app link directly to a Slack channel.",
     tags: ["integrations"],
+    requestBody: z.object({
+      appId: z.string().describe("App to share"),
+      channelId: z.string().describe("Target Slack channel ID"),
+      message: z.string().optional().describe("Optional accompanying message"),
+    }),
+    responseBody: SlackShareResultSchema,
     handler: handleShareToSlackChannel,
   },
 ];

package/src/runtime/routes/integrations/telegram.ts

@@ -16,6 +16,7 @@ import {
   setTelegramCommands,
   setTelegramConfig,
   setupTelegram,
+  TelegramConfigResultSchema,
 } from "../../../daemon/handlers/config-telegram.js";
 import { ACTOR_PRINCIPALS } from "../../auth/route-policy.js";
 import { BadRequestError } from "../errors.js";
@@ -87,6 +88,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Get Telegram config",
     description: "Check current Telegram bot configuration status.",
     tags: ["integrations"],
+    responseBody: TelegramConfigResultSchema,
     handler: () => handleGetTelegramConfig(),
   },
   {
@@ -104,6 +106,7 @@ export const ROUTES: RouteDefinition[] = [
     requestBody: z.object({
       botToken: z.string().describe("Telegram bot token"),
     }),
+    responseBody: TelegramConfigResultSchema,
   },
   {
     operationId: "integrations_telegram_config_delete",
@@ -116,6 +119,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Clear Telegram config",
     description: "Clear credentials and deregister webhook.",
     tags: ["integrations"],
+    responseBody: TelegramConfigResultSchema,
     handler: () => handleClearTelegramConfig(),
   },
   {
@@ -129,6 +133,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Register Telegram commands",
     description: "Register bot commands with the Telegram API.",
     tags: ["integrations"],
+    responseBody: TelegramConfigResultSchema,
     handler: handleSetTelegramCommands,
   },
   {
@@ -142,6 +147,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Setup Telegram",
     description: "Composite: set config + register commands.",
     tags: ["integrations"],
+    responseBody: TelegramConfigResultSchema,
     handler: handleSetupTelegram,
   },
 ];

package/src/runtime/routes/integrations/twilio.ts

@@ -36,6 +36,41 @@ import { ACTOR_PRINCIPALS } from "../../auth/route-policy.js";
 import { BadRequestError, InternalError } from "../errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "../types.js";
 
+// ---------------------------------------------------------------------------
+// Response schemas
+// ---------------------------------------------------------------------------
+
+const TwilioPhoneNumberSchema = z.object({
+  phoneNumber: z.string(),
+  friendlyName: z.string(),
+  capabilities: z.object({ voice: z.boolean() }),
+});
+
+const TwilioConfigResultSchema = z.object({
+  success: z.boolean(),
+  hasCredentials: z.boolean(),
+  accountSid: z.string().optional(),
+  phoneNumber: z.string().optional(),
+});
+
+const TwilioCredentialsResultSchema = z.object({
+  success: z.boolean(),
+  hasCredentials: z.boolean(),
+});
+
+const TwilioNumbersResultSchema = z.object({
+  success: z.boolean(),
+  hasCredentials: z.boolean(),
+  numbers: z.array(TwilioPhoneNumberSchema),
+});
+
+const TwilioNumberMutationResultSchema = z.object({
+  success: z.boolean(),
+  hasCredentials: z.boolean(),
+  phoneNumber: z.string().optional(),
+  warning: z.string().optional(),
+});
+
 // ---------------------------------------------------------------------------
 // Shared helpers
 // ---------------------------------------------------------------------------
@@ -362,6 +397,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Get Twilio config",
     description: "Return current Twilio configuration status.",
     tags: ["integrations"],
+    responseBody: TwilioConfigResultSchema,
     handler: () => handleGetTwilioConfig(),
   },
   {
@@ -380,6 +416,7 @@ export const ROUTES: RouteDefinition[] = [
       accountSid: z.string().describe("Twilio account SID"),
       authToken: z.string().describe("Twilio auth token"),
     }),
+    responseBody: TwilioCredentialsResultSchema,
   },
   {
     operationId: "integrations_twilio_credentials_delete",
@@ -392,6 +429,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Clear Twilio credentials",
     description: "Remove stored Twilio credentials.",
     tags: ["integrations"],
+    responseBody: TwilioCredentialsResultSchema,
     handler: () => handleClearTwilioCredentials(),
   },
   {
@@ -405,6 +443,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "List Twilio numbers",
     description: "List phone numbers on the Twilio account.",
     tags: ["integrations"],
+    responseBody: TwilioNumbersResultSchema,
     handler: () => handleListTwilioNumbers(),
   },
   {
@@ -418,6 +457,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Provision Twilio number",
     description: "Search for and provision a new phone number.",
     tags: ["integrations"],
+    responseBody: TwilioNumberMutationResultSchema,
     handler: handleProvisionTwilioNumber,
   },
   {
@@ -431,6 +471,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Assign Twilio number",
     description: "Assign an existing phone number to this assistant.",
     tags: ["integrations"],
+    responseBody: TwilioNumberMutationResultSchema,
     handler: handleAssignTwilioNumber,
   },
   {
@@ -444,6 +485,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Release Twilio number",
     description: "Release a phone number back to Twilio.",
     tags: ["integrations"],
+    responseBody: TwilioNumberMutationResultSchema,
     handler: handleReleaseTwilioNumber,
   },
 ];

package/src/runtime/routes/internal-telemetry-routes.ts

@@ -0,0 +1,88 @@
+/**
+ * Internal telemetry routes — receive operational signals forwarded from the
+ * gateway over the internal (service-token) transport.
+ *
+ * POST /v1/internal/telemetry/auth-fallback — record aggregated counts of
+ * requests served via the legacy loopback auth fallback. The gateway counts
+ * fallbacks in memory and flushes them here per window; the usage telemetry
+ * reporter ships the persisted rows to the platform.
+ */
+
+import { z } from "zod";
+
+import {
+  type AuthFallbackCount,
+  recordAuthFallbackCounts,
+} from "../../memory/auth-fallback-events-store.js";
+import { getLogger } from "../../util/logger.js";
+import { GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
+import { BadRequestError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+const log = getLogger("internal-telemetry-routes");
+
+const authFallbackBody = z.object({
+  window_start: z.number().int().nonnegative(),
+  window_end: z.number().int().nonnegative(),
+  counts: z
+    .array(
+      z.object({
+        guard: z.string().min(1),
+        path: z.string().min(1),
+        failure_kind: z.string().min(1),
+        count: z.number().int().positive(),
+      }),
+    )
+    .min(1),
+});
+
+function handleRecordAuthFallback({ body }: RouteHandlerArgs) {
+  const parsed = authFallbackBody.safeParse(body);
+  if (!parsed.success) {
+    throw new BadRequestError(
+      `Invalid auth-fallback payload: ${parsed.error.message}`,
+    );
+  }
+  const { window_start, window_end, counts } = parsed.data;
+  const mapped: AuthFallbackCount[] = counts.map((c) => ({
+    guard: c.guard,
+    path: c.path,
+    failureKind: c.failure_kind,
+    count: c.count,
+  }));
+
+  const recorded = recordAuthFallbackCounts(window_start, window_end, mapped);
+  if (recorded === 0) {
+    // collectUsageData disabled — counts dropped to honor the opt-out.
+    return { skipped: true };
+  }
+  log.debug({ recorded }, "Recorded auth-fallback counts");
+  return { recorded };
+}
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "internal_telemetry_auth_fallback",
+    endpoint: "internal/telemetry/auth-fallback",
+    method: "POST",
+    policy: {
+      requiredScopes: ["internal.write"],
+      allowedPrincipalTypes: GATEWAY_PRINCIPALS,
+    },
+    summary: "Record auth-fallback counts",
+    description:
+      "Receives aggregated legacy-loopback auth-fallback counts forwarded by " +
+      "the gateway and persists them for telemetry reporting.",
+    tags: ["internal", "telemetry"],
+    requestBody: authFallbackBody,
+    responseBody: z.union([
+      z.object({ recorded: z.number().int().nonnegative() }),
+      z.object({
+        skipped: z
+          .literal(true)
+          .describe("Counts dropped because usage data collection is disabled"),
+      }),
+    ]),
+    handler: handleRecordAuthFallback,
+  },
+];

package/src/runtime/routes/log-export-routes.ts

@@ -508,6 +508,10 @@ export const ROUTES: RouteDefinition[] = [
       "Export audit records, assistant logs, and config as a tar.gz archive.",
     tags: ["export"],
     requestBody: exportRequestBody,
+    responseBody: {
+      contentType: "application/gzip",
+      schema: { type: "string", format: "binary" },
+    },
     responseHeaders: {
       "Content-Type": "application/gzip",
       "Content-Disposition": 'attachment; filename="logs.tar.gz"',
@@ -532,6 +536,10 @@ export const ROUTES: RouteDefinition[] = [
       "Alias for /v1/export. Export audit records, assistant logs, and config as a tar.gz archive.",
     tags: ["export"],
     requestBody: exportRequestBody,
+    responseBody: {
+      contentType: "application/gzip",
+      schema: { type: "string", format: "binary" },
+    },
     responseHeaders: {
       "Content-Type": "application/gzip",
       "Content-Disposition": 'attachment; filename="logs.tar.gz"',

package/src/runtime/routes/memory-v2-routes.ts

@@ -210,14 +210,20 @@ async function handleGetConceptPage({
 
 const MemoryV2ListConceptPagesParams = z.object({}).strict();
 
-export type MemoryV2ListConceptPagesResult = {
-  pages: Array<{
-    slug: string;
-    bodyBytes: number;
-    edgeCount: number;
-    updatedAtMs: number;
-  }>;
-};
+export const MemoryV2ListConceptPagesResultSchema = z.object({
+  pages: z.array(
+    z.object({
+      slug: z.string(),
+      bodyBytes: z.number(),
+      edgeCount: z.number(),
+      updatedAtMs: z.number(),
+    }),
+  ),
+});
+
+export type MemoryV2ListConceptPagesResult = z.infer<
+  typeof MemoryV2ListConceptPagesResultSchema
+>;
 
 async function handleListConceptPages({
   body = {},
@@ -732,6 +738,7 @@ export const ROUTES: RouteDefinition[] = [
       "Returns slugs, body sizes, edge counts, and last-modified timestamps for every concept page on disk. Read-only; used by the desktop About → Memories surface to render a browse-able list.",
     tags: ["memory"],
     requestBody: MemoryV2ListConceptPagesParams,
+    responseBody: MemoryV2ListConceptPagesResultSchema,
   },
   {
     operationId: "memory_v2_reembed_skills",

package/src/runtime/routes/memory-v3-routes.ts

@@ -18,17 +18,29 @@
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { z } from "zod";
+
 import { getPageIndex } from "../../memory/v2/page-index.js";
-import { loadCore } from "../../memory/v3/core.js";
-import { computeV3Health, renderV3Health } from "../../memory/v3/health.js";
-import { type LeafRef, reconcileTree } from "../../memory/v3/reconcile.js";
-import { invalidateLanes } from "../../memory/v3/shadow-plugin.js";
+import { loadCore } from "../../plugins/defaults/memory-v3-shadow/core.js";
+import {
+  computeV3Health,
+  renderV3Health,
+} from "../../plugins/defaults/memory-v3-shadow/health.js";
+import {
+  type LeafRef,
+  reconcileTree,
+} from "../../plugins/defaults/memory-v3-shadow/reconcile.js";
+import { invalidateLanes } from "../../plugins/defaults/memory-v3-shadow/shadow-plugin.js";
 import {
   coreSlugs,
   loadLeafTree,
   resolveDataDir,
-} from "../../memory/v3/tree.js";
-import type { LeafPath, LeafTree, Slug } from "../../memory/v3/types.js";
+} from "../../plugins/defaults/memory-v3-shadow/tree.js";
+import type {
+  LeafPath,
+  LeafTree,
+  Slug,
+} from "../../plugins/defaults/memory-v3-shadow/types.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspaceDir } from "../../util/platform.js";
 import { ACTOR_PRINCIPALS, type RoutePolicy } from "../auth/route-policy.js";
@@ -88,18 +100,19 @@ async function loadTreeAndSlugs(deps?: MemoryV3Deps): Promise<{
 // health
 // ---------------------------------------------------------------------------
 
-export interface MemoryV3HealthResult {
+const MemoryV3HealthResultSchema = z.object({
   /** Pre-rendered, human-readable report. Empty string when all-green. */
-  rendered: string;
+  rendered: z.string(),
   /** The structural counts, for `--json` consumers. */
-  counts: {
-    unassigned: number;
-    danglingRefs: number;
-    novelClusters: number;
-    oversizedLeaves: number;
-    tinyLeaves: number;
-  };
-}
+  counts: z.object({
+    unassigned: z.number(),
+    danglingRefs: z.number(),
+    novelClusters: z.number(),
+    oversizedLeaves: z.number(),
+    tinyLeaves: z.number(),
+  }),
+});
+export type MemoryV3HealthResult = z.infer<typeof MemoryV3HealthResultSchema>;
 
 export async function handleMemoryV3Health(
   deps?: MemoryV3Deps,
@@ -123,26 +136,28 @@ export async function handleMemoryV3Health(
 // set-core
 // ---------------------------------------------------------------------------
 
-export interface MemoryV3SetCoreBody {
+const MemoryV3SetCoreBodySchema = z.object({
   /** Leaves to add to the always-on core set. */
-  add?: LeafPath[];
+  add: z.array(z.string()).optional(),
   /** Leaves to remove from the always-on core set. */
-  remove?: LeafPath[];
+  remove: z.array(z.string()).optional(),
   /**
    * When true, persist the new core to `core.json` and invalidate the lanes.
    * When false (default), compute the preview WITHOUT writing.
    */
-  write?: boolean;
-}
+  write: z.boolean().optional(),
+});
+export type MemoryV3SetCoreBody = z.infer<typeof MemoryV3SetCoreBodySchema>;
 
-export interface MemoryV3SetCoreResult {
+const MemoryV3SetCoreResultSchema = z.object({
   /** The core leaf set that would result (or did result, when `write`). */
-  nextCore: LeafPath[];
+  nextCore: z.array(z.string()),
   /** Number of unique page slugs the new core set pins always-on. */
-  alwaysOnPageCount: number;
+  alwaysOnPageCount: z.number(),
   /** Whether `core.json` was written. */
-  written: boolean;
-}
+  written: z.boolean(),
+});
+export type MemoryV3SetCoreResult = z.infer<typeof MemoryV3SetCoreResultSchema>;
 
 /** Wire-format error code for a `set-core` add referencing an unknown leaf. */
 export const MEMORY_V3_UNKNOWN_LEAF_CODE = "MEMORY_V3_UNKNOWN_LEAF";
@@ -206,11 +221,20 @@ export async function handleMemoryV3SetCore(
 // reconcile
 // ---------------------------------------------------------------------------
 
-export interface MemoryV3ReconcileResult {
-  renames: Array<{ id?: string; oldPath: LeafPath; newPath: LeafPath }>;
-  deleted: LeafPath[];
-  prunedCore: LeafPath[];
-}
+const MemoryV3ReconcileResultSchema = z.object({
+  renames: z.array(
+    z.object({
+      id: z.string().optional(),
+      oldPath: z.string(),
+      newPath: z.string(),
+    }),
+  ),
+  deleted: z.array(z.string()),
+  prunedCore: z.array(z.string()),
+});
+export type MemoryV3ReconcileResult = z.infer<
+  typeof MemoryV3ReconcileResultSchema
+>;
 
 /**
  * Reconcile page + core references against the live on-disk tree.
@@ -253,9 +277,12 @@ async function loadPrevLeaves(dataDir: string): Promise<LeafRef[]> {
 // rebuild-index
 // ---------------------------------------------------------------------------
 
-export interface MemoryV3RebuildIndexResult {
-  ok: true;
-}
+const MemoryV3RebuildIndexResultSchema = z.object({
+  ok: z.literal(true),
+});
+export type MemoryV3RebuildIndexResult = z.infer<
+  typeof MemoryV3RebuildIndexResultSchema
+>;
 
 /**
  * Invalidate the v3 shadow lanes so the next turn rebuilds the tree/needle
@@ -299,6 +326,7 @@ export const ROUTES: RouteDefinition[] = [
     handler: () => handleMemoryV3Health(),
     summary: "Print the v3 structural health report (read-only)",
     tags: ["memory"],
+    responseBody: MemoryV3HealthResultSchema,
   },
   {
     operationId: "memory_v3_set_core",
@@ -317,6 +345,8 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Add/remove always-on core leaves (validates + previews cost)",
     tags: ["memory"],
+    requestBody: MemoryV3SetCoreBodySchema,
+    responseBody: MemoryV3SetCoreResultSchema,
   },
   {
     operationId: "memory_v3_reconcile",
@@ -327,6 +357,7 @@ export const ROUTES: RouteDefinition[] = [
     summary:
       "v1 convergence/prune pass over page+core refs (no rename detection without a prior snapshot)",
     tags: ["memory"],
+    responseBody: MemoryV3ReconcileResultSchema,
   },
   {
     operationId: "memory_v3_rebuild_index",
@@ -336,5 +367,6 @@ export const ROUTES: RouteDefinition[] = [
     handler: () => handleMemoryV3RebuildIndex(),
     summary: "Invalidate the v3 lanes so the next turn rebuilds",
     tags: ["memory"],
+    responseBody: MemoryV3RebuildIndexResultSchema,
   },
 ];