@vellumai/assistant 0.8.7 → 0.8.8

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

@@ -14,6 +14,8 @@
  *     registered callback routes for this assistant.
  */
 
+import { z } from "zod";
+
 import { isPlatformRemote } from "../../config/env-registry.js";
 import {
   registerCallbackRoute,
@@ -47,13 +49,80 @@ const CREDENTIAL_KEYS = {
   userId: { service: "vellum", field: "platform_user_id" },
 } as const;
 
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+const VelayTunnelStatusSchema = z.object({
+  connected: z.boolean(),
+  publicUrl: z.string().nullable(),
+});
+
+const PlatformStatusResponseSchema = z.object({
+  isPlatform: z.boolean(),
+  baseUrl: z.string(),
+  assistantId: z.string(),
+  hasAssistantApiKey: z.boolean(),
+  hasWebhookSecret: z.boolean(),
+  available: z.boolean(),
+  organizationId: z.string().nullable(),
+  userId: z.string().nullable(),
+  velayTunnel: VelayTunnelStatusSchema.nullable(),
+});
+type PlatformStatusResponse = z.infer<typeof PlatformStatusResponseSchema>;
+
+const PlatformConnectResponseSchema = z.object({
+  alreadyConnected: z.boolean().optional(),
+  baseUrl: z.string().optional(),
+  showPlatformLogin: z.boolean().optional(),
+});
+type PlatformConnectResponse = z.infer<typeof PlatformConnectResponseSchema>;
+
+const PlatformDisconnectResponseSchema = z.object({
+  disconnected: z.literal(true),
+  previousBaseUrl: z.string().nullable(),
+});
+type PlatformDisconnectResponse = z.infer<
+  typeof PlatformDisconnectResponseSchema
+>;
+
+const CallbackRouteRegisterRequestSchema = z.object({
+  path: z.string(),
+  type: z.string(),
+});
+
+const CallbackRouteRegisterResponseSchema = z.object({
+  callbackUrl: z.string(),
+  callbackPath: z.string(),
+  type: z.string(),
+});
+type CallbackRouteRegisterResponse = z.infer<
+  typeof CallbackRouteRegisterResponseSchema
+>;
+
+const CallbackRouteSchema = z.object({
+  id: z.string(),
+  assistant_id: z.string(),
+  type: z.string(),
+  callback_path: z.string(),
+  callback_url: z.string(),
+  source_identifier: z.string().nullable(),
+});
+
+const CallbackRoutesListResponseSchema = z.object({
+  routes: z.array(CallbackRouteSchema),
+});
+type CallbackRoutesListResponse = z.infer<
+  typeof CallbackRoutesListResponseSchema
+>;
+
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
 
 async function handlePlatformStatus(
   _args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<PlatformStatusResponse> {
   const [context, velayTunnel] = await Promise.all([
     resolvePlatformCallbackRegistrationContext(),
     ipcGetVelayStatus().catch(() => null),
@@ -94,7 +163,7 @@ async function handlePlatformStatus(
 
 async function handlePlatformConnect(
   _args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<PlatformConnectResponse> {
   // Check if already connected
   const [existingUrl, existingApiKey] = await Promise.all([
     getSecureKeyAsync(
@@ -128,7 +197,7 @@ async function handlePlatformConnect(
 
 async function handlePlatformDisconnect(
   _args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<PlatformDisconnectResponse> {
   // Reject if running inside a platform host
   if (isPlatformRemote()) {
     throw new UnprocessableEntityError(
@@ -197,7 +266,7 @@ async function handlePlatformDisconnect(
 
 async function handleCallbackRoutesRegister(
   args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<CallbackRouteRegisterResponse> {
   const { path, type } = (args.body ?? {}) as {
     path?: string;
     type?: string;
@@ -235,7 +304,7 @@ async function handleCallbackRoutesRegister(
 
 async function handleCallbackRoutesList(
   _args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<CallbackRoutesListResponse> {
   const context = await resolvePlatformCallbackRegistrationContext();
 
   if (!context.platformBaseUrl || !context.authHeader) {
@@ -274,6 +343,7 @@ async function handleCallbackRoutesList(
     type: string;
     callback_path: string;
     callback_url: string;
+    source_identifier: string | null;
   }>;
 
   return { routes };
@@ -297,6 +367,7 @@ export const ROUTES: RouteDefinition[] = [
       "Aggregates platform context, credentials, assistant ID, webhook secret, and Velay tunnel status.",
     tags: ["platform"],
     handler: handlePlatformStatus,
+    responseBody: PlatformStatusResponseSchema,
   },
   {
     operationId: "platform_connect",
@@ -311,6 +382,7 @@ export const ROUTES: RouteDefinition[] = [
       "Checks existing credentials and emits the show_platform_login signal for connected clients to show a login UI.",
     tags: ["platform"],
     handler: handlePlatformConnect,
+    responseBody: PlatformConnectResponseSchema,
   },
   {
     operationId: "platform_disconnect",
@@ -325,6 +397,7 @@ export const ROUTES: RouteDefinition[] = [
       "Deletes stored platform credentials and emits platform_disconnected signal to connected clients.",
     tags: ["platform"],
     handler: handlePlatformDisconnect,
+    responseBody: PlatformDisconnectResponseSchema,
   },
   {
     operationId: "platform_callback_routes_register",
@@ -339,6 +412,8 @@ export const ROUTES: RouteDefinition[] = [
       "Registers a callback route with the platform gateway for inbound provider webhooks.",
     tags: ["platform"],
     handler: handleCallbackRoutesRegister,
+    requestBody: CallbackRouteRegisterRequestSchema,
+    responseBody: CallbackRouteRegisterResponseSchema,
   },
   {
     operationId: "platform_callback_routes_list",
@@ -353,5 +428,6 @@ export const ROUTES: RouteDefinition[] = [
       "Lists all callback routes registered with the platform for this assistant.",
     tags: ["platform"],
     handler: handleCallbackRoutesList,
+    responseBody: CallbackRoutesListResponseSchema,
   },
 ];

package/src/runtime/routes/playground/__tests__/force-compact.test.ts

@@ -65,8 +65,12 @@ function makeFakeConversation(
     ...options.result,
   };
 
+  let processing = options.processing ?? false;
   const fake = {
-    processing: options.processing ?? false,
+    isProcessing: () => processing,
+    setProcessing: (value: boolean) => {
+      processing = value;
+    },
     getMessages(): Message[] {
       if (!returnedAfter && calls === 0) return messagesBefore;
       return messagesAfter;
@@ -85,9 +89,7 @@ function makeFakeConversation(
 }
 
 function findRoute() {
-  const route = ROUTES.find(
-    (r) => r.operationId === "playgroundForceCompact",
-  );
+  const route = ROUTES.find((r) => r.operationId === "playgroundForceCompact");
   if (!route) throw new Error("force-compact route not registered");
   return route;
 }

package/src/runtime/routes/playground/force-compact.ts

@@ -35,7 +35,7 @@ export const ROUTES: RouteDefinition[] = [
         throwConversationNotFound(id);
       }
 
-      if (conversation.processing) {
+      if (conversation.isProcessing()) {
         throw new ConflictError(
           "Compaction already in progress for this conversation",
         );

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

@@ -23,6 +23,10 @@ const RenameConversationBody = z.object({
   title: z.string().min(1),
 });
 
+const RenameConversationResponse = z.object({
+  ok: z.literal(true),
+});
+
 export const ROUTES: RouteDefinition[] = [
   {
     operationId: "rename_conversation",
@@ -36,6 +40,7 @@ export const ROUTES: RouteDefinition[] = [
     description: "Update the display title of a conversation.",
     tags: ["conversations"],
     requestBody: RenameConversationBody,
+    responseBody: RenameConversationResponse,
     handler: ({ body, headers }) => {
       const parsed = RenameConversationBody.safeParse(body);
       if (!parsed.success) {

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

@@ -11,6 +11,7 @@ import { getOrCreateConversation } from "../../daemon/conversation-store.js";
 import { INTERNAL_GUARDIAN_TRUST_CONTEXT } from "../../daemon/trust-context.js";
 import { bootstrapConversation } from "../../memory/conversation-bootstrap.js";
 import { getConversation } from "../../memory/conversation-crud.js";
+import { getUsageCostForConversationWindow } from "../../memory/llm-usage-store.js";
 import { normalizeScheduleSyntax } from "../../schedule/recurrence-types.js";
 import {
   runScript,
@@ -27,10 +28,13 @@ import {
   getSchedule,
   getScheduleRuns,
   listSchedules,
+  setScheduleRunConversationId,
   updateSchedule,
 } from "../../schedule/schedule-store.js";
+import { getScheduleUsageSummaries } from "../../schedule/schedule-usage-store.js";
 import { getLogger } from "../../util/logger.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import { parseEpochMillisRange } from "./epoch-millis-range.js";
 import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -57,6 +61,9 @@ const scheduleSchema = z.object({
   maxRetries: z.number(),
   retryBackoffMs: z.number(),
   timeoutMs: z.number().nullable(),
+  createdFromConversationId: z.string().nullable(),
+  createdFromConversationExists: z.boolean(),
+  createdFromConversationArchivedAt: z.number().nullable(),
   description: z.string().nullable(),
   mode: z.enum(["notify", "execute", "script", "wake"]),
   status: z.enum(["active", "firing", "fired", "cancelled"]),
@@ -76,48 +83,96 @@ const scheduleRunSchema = z.object({
   output: z.string().nullable(),
   error: z.string().nullable(),
   conversationId: z.string().nullable(),
+  conversationExists: z.boolean(),
+  conversationArchivedAt: z.number().nullable(),
+  estimatedCostUsd: z.number(),
   createdAt: z.number(),
 });
 
+const scheduleUsageSummarySchema = z.object({
+  scheduleId: z.string(),
+  runCount: z.number(),
+  totalEstimatedCostUsd: z.number(),
+  eventCount: z.number(),
+});
+
 // ---------------------------------------------------------------------------
 // Handlers (transport-agnostic)
 // ---------------------------------------------------------------------------
 
+interface CreatedFromConversationState {
+  exists: boolean;
+  archivedAt: number | null;
+}
+
+function getCreatedFromConversationState(
+  conversationId: string | null,
+  cache: Map<string, CreatedFromConversationState>,
+): CreatedFromConversationState {
+  if (!conversationId) {
+    return { exists: false, archivedAt: null };
+  }
+
+  const cached = cache.get(conversationId);
+  if (cached) return cached;
+
+  const conversation = getConversation(conversationId);
+  const state = {
+    exists: conversation !== null,
+    archivedAt: conversation?.archivedAt ?? null,
+  };
+  cache.set(conversationId, state);
+  return state;
+}
+
 function handleListSchedules(queryParams: Record<string, string>) {
   const includeAll = queryParams.include_all === "true";
   const jobs = listSchedules();
   const filtered = includeAll
     ? jobs
     : jobs.filter((j) => j.createdBy !== "defer");
+  const sourceConversationCache = new Map<
+    string,
+    CreatedFromConversationState
+  >();
   return {
-    schedules: filtered.map((j) => ({
-      id: j.id,
-      name: j.name,
-      enabled: j.enabled,
-      syntax: j.syntax,
-      expression: j.expression,
-      cronExpression: j.cronExpression,
-      timezone: j.timezone,
-      message: j.message,
-      script: j.script,
-      nextRunAt: j.nextRunAt,
-      lastRunAt: j.lastRunAt,
-      lastStatus: j.lastStatus,
-      retryCount: j.retryCount,
-      maxRetries: j.maxRetries,
-      retryBackoffMs: j.retryBackoffMs,
-      timeoutMs: j.timeoutMs,
-      description:
-        j.syntax === "cron"
-          ? describeCronExpression(j.cronExpression)
-          : j.expression,
-      mode: j.mode,
-      status: j.status,
-      routingIntent: j.routingIntent,
-      reuseConversation: j.reuseConversation,
-      wakeConversationId: j.wakeConversationId,
-      isOneShot: j.cronExpression == null,
-    })),
+    schedules: filtered.map((j) => {
+      const sourceConversation = getCreatedFromConversationState(
+        j.createdFromConversationId,
+        sourceConversationCache,
+      );
+      return {
+        id: j.id,
+        name: j.name,
+        enabled: j.enabled,
+        syntax: j.syntax,
+        expression: j.expression,
+        cronExpression: j.cronExpression,
+        timezone: j.timezone,
+        message: j.message,
+        script: j.script,
+        nextRunAt: j.nextRunAt,
+        lastRunAt: j.lastRunAt,
+        lastStatus: j.lastStatus,
+        retryCount: j.retryCount,
+        maxRetries: j.maxRetries,
+        retryBackoffMs: j.retryBackoffMs,
+        timeoutMs: j.timeoutMs,
+        createdFromConversationId: j.createdFromConversationId,
+        createdFromConversationExists: sourceConversation.exists,
+        createdFromConversationArchivedAt: sourceConversation.archivedAt,
+        description:
+          j.syntax === "cron"
+            ? describeCronExpression(j.cronExpression)
+            : j.expression,
+        mode: j.mode,
+        status: j.status,
+        routingIntent: j.routingIntent,
+        reuseConversation: j.reuseConversation,
+        wakeConversationId: j.wakeConversationId,
+        isOneShot: j.cronExpression == null,
+      };
+    }),
   };
 }
 
@@ -291,22 +346,42 @@ function handleListScheduleRuns(
     ? Math.min(Math.max(Math.floor(rawLimit), 1), 100)
     : 10;
   const runs = getScheduleRuns(id, limit);
+  const now = Date.now();
   return {
-    runs: runs.map((r) => ({
-      id: r.id,
-      jobId: r.jobId,
-      status: r.status,
-      startedAt: r.startedAt,
-      finishedAt: r.finishedAt,
-      durationMs: r.durationMs,
-      output: r.output,
-      error: r.error,
-      conversationId: r.conversationId,
-      createdAt: r.createdAt,
-    })),
+    runs: runs.map((r) => {
+      const conversation = r.conversationId
+        ? getConversation(r.conversationId)
+        : null;
+      return {
+        id: r.id,
+        jobId: r.jobId,
+        status: r.status,
+        startedAt: r.startedAt,
+        finishedAt: r.finishedAt,
+        durationMs: r.durationMs,
+        output: r.output,
+        error: r.error,
+        conversationId: r.conversationId,
+        conversationExists: conversation != null,
+        conversationArchivedAt: conversation?.archivedAt ?? null,
+        estimatedCostUsd: r.conversationId
+          ? getUsageCostForConversationWindow({
+              conversationId: r.conversationId,
+              from: r.startedAt,
+              to: r.finishedAt ?? now,
+            })
+          : 0,
+        createdAt: r.createdAt,
+      };
+    }),
   };
 }
 
+function handleScheduleUsageSummary(queryParams: Record<string, string>) {
+  const range = parseEpochMillisRange(queryParams);
+  return { summaries: getScheduleUsageSummaries(range) };
+}
+
 // ---------------------------------------------------------------------------
 // Shared route definitions (HTTP + IPC)
 // ---------------------------------------------------------------------------
@@ -337,6 +412,40 @@ export const ROUTES: RouteDefinition[] = [
     handler: ({ queryParams }: RouteHandlerArgs) =>
       handleListSchedules(queryParams ?? {}),
   },
+  {
+    operationId: "getScheduleUsageSummary",
+    endpoint: "schedules/usage-summary",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Get schedule usage summaries",
+    description:
+      "Return per-schedule run counts and usage totals for a time range.",
+    tags: ["schedules"],
+    queryParams: [
+      {
+        name: "from",
+        type: "integer",
+        required: true,
+        description: "Start epoch millis (required)",
+      },
+      {
+        name: "to",
+        type: "integer",
+        required: true,
+        description: "End epoch millis (required)",
+      },
+    ],
+    responseBody: z.object({
+      summaries: z
+        .array(scheduleUsageSummarySchema)
+        .describe("Schedule usage summary rows"),
+    }),
+    handler: ({ queryParams }: RouteHandlerArgs) =>
+      handleScheduleUsageSummary(queryParams ?? {}),
+  },
   {
     operationId: "createSchedule",
     endpoint: "schedules",
@@ -551,6 +660,7 @@ async function handleRunScheduleNow(id: string) {
   const taskMatch = schedule.message.match(/^run_task:(\S+)$/);
   if (taskMatch) {
     const taskId = taskMatch[1];
+    const runId = createScheduleRun(schedule.id, null);
     try {
       log.info(
         { jobId: schedule.id, name: schedule.name, taskId },
@@ -577,7 +687,7 @@ async function handleRunScheduleNow(id: string) {
         },
       );
 
-      const runId = createScheduleRun(schedule.id, result.conversationId);
+      setScheduleRunConversationId(runId, result.conversationId);
       if (result.status === "failed") {
         completeScheduleRun(runId, {
           status: "error",
@@ -598,7 +708,7 @@ async function handleRunScheduleNow(id: string) {
         origin: "schedule",
         systemHint: `Schedule (manual): ${schedule.name}`,
       });
-      const runId = createScheduleRun(schedule.id, fallbackConversation.id);
+      setScheduleRunConversationId(runId, fallbackConversation.id);
       completeScheduleRun(runId, { status: "error", error: message });
     }
     return handleListSchedules({});

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

@@ -684,9 +684,21 @@ export const ROUTES: RouteDefinition[] = [
     tags: ["secrets"],
     responseBody: z.object({
       secrets: z
-        .array(z.unknown())
+        .array(
+          z.object({
+            type: z.enum(["api_key", "credential"]),
+            name: z.string(),
+          }),
+        )
         .describe("List of secret metadata entries, each with type and name"),
-      accounts: z.array(z.unknown()).describe("Alias for secrets (same data)"),
+      accounts: z
+        .array(
+          z.object({
+            type: z.enum(["api_key", "credential"]),
+            name: z.string(),
+          }),
+        )
+        .describe("Alias for secrets (same data)"),
     }),
     handler: handleListSecrets,
   },

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

@@ -26,6 +26,7 @@ import {
   uninstallSkill,
   updateSkill,
 } from "../../daemon/handlers/skills.js";
+import { getCategories } from "../../skills/categories-cache.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -41,19 +42,11 @@ const slimSkillBase = {
   id: z.string(),
   name: z.string(),
   description: z.string(),
+  icon: z.string().optional(),
   emoji: z.string().optional(),
   kind: z.enum(["bundled", "installed", "catalog"]),
   status: z.enum(["enabled", "disabled", "available"]),
-  category: z.enum([
-    "communication",
-    "productivity",
-    "development",
-    "media",
-    "automation",
-    "webSocial",
-    "knowledge",
-    "integration",
-  ]),
+  category: z.string(),
 };
 
 const slimSkillSchema = z.discriminatedUnion("origin", [
@@ -220,6 +213,33 @@ export const ROUTES: RouteDefinition[] = [
       return { skills };
     },
   },
+  {
+    operationId: "listSkillCategories",
+    endpoint: "skills/categories",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "List skill categories",
+    description:
+      "Return all skill category definitions with labels, icons, and descriptions.",
+    tags: ["skills"],
+    responseBody: z.object({
+      categories: z.array(
+        z.object({
+          slug: z.string(),
+          label: z.string(),
+          description: z.string(),
+          icon: z.string(),
+        }),
+      ),
+    }),
+    handler: async () => {
+      const categories = await getCategories();
+      return { categories };
+    },
+  },
   {
     operationId: "getSkillFileContent",
     endpoint: "skills/:id/files/content",
@@ -546,10 +566,19 @@ export const ROUTES: RouteDefinition[] = [
     description: "Install a skill by slug, URL, or spec.",
     tags: ["skills"],
     requestBody: z.object({
-      slug: z.string().describe("Skill slug"),
-      url: z.string().describe("Skill URL"),
-      spec: z.string().describe("Skill spec"),
-      version: z.string(),
+      slug: z
+        .string()
+        .optional()
+        .describe("Skill slug. One of slug, url, or spec is required."),
+      url: z
+        .string()
+        .optional()
+        .describe("Skill URL. One of slug, url, or spec is required."),
+      spec: z
+        .string()
+        .optional()
+        .describe("Skill spec. One of slug, url, or spec is required."),
+      version: z.string().optional().describe("Specific version to install"),
       origin: z
         .enum(["clawhub", "skillssh"])
         .optional()