@vellumai/assistant 0.8.0 → 0.8.2

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

@@ -0,0 +1,259 @@
+/**
+ * Route handler for resolving pending question prompts.
+ *
+ * POST /v1/question-response — a client (UI or remote channel) submits the
+ * user's selection for a pending ask-question interaction registered by
+ * {@link QuestionPrompter}. Two top-level shapes are accepted:
+ *
+ *  - `kind: "submit"` carries a `responses` array — one entry per question in
+ *    the original batch. The web client builds this locally and POSTs it once
+ *    the user is done revising the card.
+ *  - `kind: "close"` records that the user dismissed the card without
+ *    answering; every entry is reported as `skipped`.
+ *
+ * For backwards-compat we also accept the prior single-question shape
+ * (`{ kind: "option" | "free_text", ... }`) as syntactic sugar for a
+ * one-element batch. That branch only succeeds against a single-question
+ * batch — multi-question batches reject it with a helpful error.
+ *
+ * Cross-talk safety: pending interactions of other kinds (`confirmation`,
+ * `secret`, host_*, etc.) return 404 here rather than being mis-resolved.
+ */
+import { z } from "zod";
+
+import {
+  buildBatchEntries,
+  type QuestionBatchMetadata,
+  type QuestionBatchSubmission,
+  QuestionBatchValidationError,
+  type QuestionPromptResult,
+} from "../../permissions/question-prompter.js";
+import { getLogger } from "../../util/logger.js";
+import * as pendingInteractions from "../pending-interactions.js";
+import { BadRequestError, NotFoundError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+const log = getLogger("question-routes");
+
+// ── Batched (current) body shape ────────────────────────────────────
+
+const SubmitEntry = z.discriminatedUnion("kind", [
+  z.object({
+    questionId: z.string(),
+    kind: z.literal("option"),
+    optionId: z.string(),
+  }),
+  z.object({
+    questionId: z.string(),
+    kind: z.literal("free_text"),
+    text: z.string(),
+  }),
+  z.object({
+    questionId: z.string(),
+    kind: z.literal("skip"),
+  }),
+]);
+
+const SubmitBody = z.object({
+  requestId: z.string(),
+  kind: z.literal("submit"),
+  responses: z.array(SubmitEntry).min(1),
+});
+
+const CloseBody = z.object({
+  requestId: z.string(),
+  kind: z.literal("close"),
+});
+
+// ── Legacy single-question body shape (sugar for one-element batch) ──
+
+const LegacyOptionBody = z.object({
+  requestId: z.string(),
+  kind: z.literal("option"),
+  optionId: z.string(),
+});
+
+const LegacyFreeTextBody = z.object({
+  requestId: z.string(),
+  kind: z.literal("free_text"),
+  text: z.string(),
+});
+
+// All four variants are mutually exclusive by their `kind` literal, so use
+// `discriminatedUnion` rather than plain `union`. The generated OpenAPI then
+// emits `oneOf` for the body (matching the pre-batched-shape spec) instead
+// of the looser `anyOf` that `z.union` produces.
+const QuestionResponseBody = z.discriminatedUnion("kind", [
+  SubmitBody,
+  CloseBody,
+  LegacyOptionBody,
+  LegacyFreeTextBody,
+]);
+
+type SubmitBody = z.infer<typeof SubmitBody>;
+type CloseBody = z.infer<typeof CloseBody>;
+type LegacyOptionBody = z.infer<typeof LegacyOptionBody>;
+type LegacyFreeTextBody = z.infer<typeof LegacyFreeTextBody>;
+type QuestionResponseBody = z.infer<typeof QuestionResponseBody>;
+
+/**
+ * POST /v1/question-response — resolve a pending ask-question interaction.
+ */
+function handleQuestionResponse({ body }: RouteHandlerArgs) {
+  const parsed = QuestionResponseBody.safeParse(body);
+  if (!parsed.success) {
+    throw new BadRequestError(
+      `Invalid question response body: ${parsed.error.message}`,
+    );
+  }
+
+  const response: QuestionResponseBody = parsed.data;
+  const { requestId } = response;
+
+  const interaction = pendingInteractions.get(requestId);
+  if (!interaction || interaction.kind !== "question") {
+    log.warn(
+      { requestId, foundKind: interaction?.kind },
+      "Question response for unknown or wrong-kind requestId",
+    );
+    throw new NotFoundError(
+      "No pending question interaction found for this requestId",
+    );
+  }
+
+  // Build + validate the result BEFORE touching `pendingInteractions`, so a
+  // bad payload leaves the pending interaction (and its timer) intact and the
+  // user gets another chance to submit a correct batch.
+  let result: QuestionPromptResult;
+  try {
+    if (response.kind === "close") {
+      const { orderedIds } = readBatchMetadata(interaction);
+      result = {
+        entries: orderedIds.map((id) => ({
+          questionId: id,
+          decision: "skipped" as const,
+        })),
+        overall: "closed",
+      };
+    } else {
+      const submissions = buildSubmissions(response, interaction);
+      result = buildCompletedResult(submissions, interaction);
+    }
+  } catch (err) {
+    if (err instanceof QuestionBatchValidationError) {
+      throw new BadRequestError(err.message);
+    }
+    throw err;
+  }
+
+  // Validation passed — deregister now to clear the prompter timer, then
+  // hand the result to the prompter's caller via rpcResolve.
+  pendingInteractions.resolve(requestId);
+
+  log.info(
+    {
+      requestId,
+      overall: result.overall,
+      conversationId: interaction.conversationId,
+    },
+    "Question resolved",
+  );
+
+  (interaction.rpcResolve as
+    | ((value: QuestionPromptResult) => void)
+    | undefined)?.(result);
+
+  return { success: true };
+}
+
+/**
+ * Normalize the incoming body to a `QuestionBatchSubmission[]` for the
+ * submit/legacy paths. Returns `null` for the `close` path (no submissions).
+ */
+function buildSubmissions(
+  body: SubmitBody | LegacyOptionBody | LegacyFreeTextBody,
+  interaction: ReturnType<typeof pendingInteractions.get>,
+): QuestionBatchSubmission[] {
+  if (body.kind === "submit") return body.responses;
+
+  // Legacy single-question shim: synthesize a one-element batch. The
+  // prompter stashed the ordered ids on the interaction metadata so we can
+  // pick the (single) target questionId here.
+  const { orderedIds } = readBatchMetadata(interaction);
+  if (orderedIds.length === 0) {
+    throw new QuestionBatchValidationError(
+      "Legacy single-question payload requires a registered batch with at least one question",
+    );
+  }
+  if (orderedIds.length > 1) {
+    throw new QuestionBatchValidationError(
+      'Legacy single-question payload cannot answer a multi-question batch; submit `{ kind: "submit", responses: [...] }` covering every question instead.',
+    );
+  }
+  const questionId = orderedIds[0]!;
+  if (body.kind === "option") {
+    return [{ questionId, kind: "option", optionId: body.optionId }];
+  }
+  return [{ questionId, kind: "free_text", text: body.text }];
+}
+
+/**
+ * Build a `completed` QuestionPromptResult from a batched submission and the
+ * per-question metadata the prompter stashed on the interaction. Delegates
+ * the validation + ordering loop to {@link buildBatchEntries} so the
+ * prompter and the route share a single implementation.
+ */
+function buildCompletedResult(
+  submissions: QuestionBatchSubmission[],
+  interaction: ReturnType<typeof pendingInteractions.get>,
+): QuestionPromptResult {
+  const { orderedIds, optionsById } = readBatchMetadata(interaction);
+  if (orderedIds.length === 0) {
+    throw new QuestionBatchValidationError(
+      "No registered question ids for this batch",
+    );
+  }
+  const entries = buildBatchEntries(
+    orderedIds,
+    (qid, oid) => (optionsById[qid] ?? []).includes(oid),
+    new Set(Object.keys(optionsById)),
+    submissions,
+  );
+  return { entries, overall: "completed" };
+}
+
+/**
+ * Pull the prompter-stashed batch bookkeeping off a pending interaction.
+ * Returns empty defaults if the metadata is absent.
+ */
+function readBatchMetadata(
+  interaction: ReturnType<typeof pendingInteractions.get>,
+): QuestionBatchMetadata {
+  const meta = interaction?.metadata as Partial<QuestionBatchMetadata> | undefined;
+  return {
+    orderedIds: meta?.orderedIds ?? [],
+    optionsById: meta?.optionsById ?? {},
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "question_response",
+    endpoint: "question-response",
+    method: "POST",
+    handler: handleQuestionResponse,
+    requireGuardian: true,
+    summary: "Resolve a pending ask-question prompt",
+    description:
+      "Submit the user's batched response (or close the card) for a pending question prompt by requestId. Legacy single-question payloads remain accepted as syntactic sugar for a one-element batch.",
+    tags: ["approvals"],
+    requestBody: QuestionResponseBody,
+    responseBody: z.object({
+      success: z.boolean(),
+    }),
+  },
+];

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

@@ -13,9 +13,7 @@ import {
   getConversation,
   updateConversationTitle,
 } from "../../memory/conversation-crud.js";
-import { getLogger } from "../../util/logger.js";
-import { buildAssistantEvent } from "../assistant-event.js";
-import { assistantEventHub } from "../assistant-event-hub.js";
+import { publishConversationTitleChanged } from "../sync/resource-sync-events.js";
 import { BadRequestError, NotFoundError } from "./errors.js";
 import type { RouteDefinition } from "./types.js";
 
@@ -24,8 +22,6 @@ const RenameConversationBody = z.object({
   title: z.string().min(1),
 });
 
-const log = getLogger("rename-conversation-routes");
-
 export const ROUTES: RouteDefinition[] = [
   {
     operationId: "rename_conversation",
@@ -50,34 +46,7 @@ export const ROUTES: RouteDefinition[] = [
 
       updateConversationTitle(conversationId, title, 0);
 
-      assistantEventHub
-        .publish(
-          buildAssistantEvent(
-            {
-              type: "conversation_title_updated",
-              conversationId,
-              title,
-            },
-            conversationId,
-          ),
-        )
-        .catch((err) => {
-          log.warn({ err }, "Failed to publish conversation_title_updated");
-        });
-
-      assistantEventHub
-        .publish(
-          buildAssistantEvent({
-            type: "conversation_list_invalidated",
-            reason: "renamed",
-          }),
-        )
-        .catch((err) => {
-          log.warn(
-            { err },
-            "Failed to publish conversation_list_invalidated for rename",
-          );
-        });
+      publishConversationTitleChanged(conversationId, title);
 
       return { ok: true };
     },

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

@@ -11,10 +11,12 @@ 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 { normalizeScheduleSyntax } from "../../schedule/recurrence-types.js";
 import { runScript } from "../../schedule/run-script.js";
 import {
   cancelSchedule,
   completeScheduleRun,
+  createSchedule,
   createScheduleRun,
   deleteSchedule,
   describeCronExpression,
@@ -71,6 +73,54 @@ function handleListSchedules(queryParams: Record<string, string>) {
   };
 }
 
+function handleCreateSchedule(body: Record<string, unknown>) {
+  const name = typeof body.name === "string" ? body.name.trim() : "";
+  const expression =
+    typeof body.expression === "string" ? body.expression.trim() : "";
+  const message = typeof body.message === "string" ? body.message : "";
+  const timezoneRaw =
+    typeof body.timezone === "string" ? body.timezone.trim() : "";
+  const timezone = timezoneRaw === "" ? null : timezoneRaw;
+  const enabled = body.enabled !== false;
+  const mode = (body.mode as string | undefined) ?? "execute";
+
+  if (!name) throw new BadRequestError("name is required");
+  if (!expression) throw new BadRequestError("expression is required");
+  if (!message) throw new BadRequestError("message is required");
+
+  // The settings UI only exposes execute mode for now. Other modes
+  // remain reachable via the schedule_create LLM tool.
+  if (mode !== "execute") {
+    throw new BadRequestError(
+      "Only 'execute' mode is supported by this endpoint",
+    );
+  }
+
+  const normalized = normalizeScheduleSyntax({ expression });
+  if (!normalized) {
+    throw new BadRequestError(
+      "expression could not be parsed as cron or rrule",
+    );
+  }
+
+  try {
+    const job = createSchedule({
+      name,
+      message,
+      mode: "execute",
+      enabled,
+      timezone,
+      expression: normalized.expression,
+      syntax: normalized.syntax,
+    });
+    log.info({ id: job.id, name: job.name }, "Schedule created");
+  } catch (err) {
+    if (err instanceof Error) throw new BadRequestError(err.message);
+    throw err;
+  }
+  return handleListSchedules({});
+}
+
 function handleToggleSchedule(id: string, body: Record<string, unknown>) {
   const enabled = body.enabled;
   if (typeof enabled !== "boolean") {
@@ -227,6 +277,35 @@ export const ROUTES: RouteDefinition[] = [
     handler: ({ queryParams }: RouteHandlerArgs) =>
       handleListSchedules(queryParams ?? {}),
   },
+  {
+    operationId: "createSchedule",
+    endpoint: "schedules",
+    method: "POST",
+    policyKey: "schedules",
+    summary: "Create schedule",
+    description:
+      "Create a new recurring schedule. Currently restricted to mode='execute'.",
+    tags: ["schedules"],
+    requestBody: z.object({
+      name: z.string().describe("Display name"),
+      expression: z.string().describe("Cron or RRULE expression"),
+      message: z.string().describe("Message body to execute on each fire"),
+      timezone: z
+        .string()
+        .nullable()
+        .describe("IANA timezone, e.g. America/New_York")
+        .optional(),
+      enabled: z
+        .boolean()
+        .describe("Whether the schedule starts active (default true)")
+        .optional(),
+      mode: z.string().describe("Currently must be 'execute'").optional(),
+    }),
+    responseBody: z.object({
+      schedules: z.array(z.unknown()).describe("Updated schedule list"),
+    }),
+    handler: ({ body }: RouteHandlerArgs) => handleCreateSchedule(body ?? {}),
+  },
   {
     operationId: "listScheduleRuns",
     endpoint: "schedules/:id/runs",

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

@@ -0,0 +1,291 @@
+/**
+ * Transport-agnostic routes for email sequence management.
+ *
+ * Handles listing, inspecting, pausing, resuming sequences,
+ * cancelling enrollments, viewing stats, and managing guardrails.
+ */
+
+import { z } from "zod";
+
+import { getDb } from "../../memory/db-connection.js";
+import {
+  getGuardrailConfig,
+  setGuardrailConfig,
+} from "../../sequence/guardrails.js";
+import {
+  countActiveEnrollments,
+  exitEnrollment,
+  getSequence,
+  listEnrollments,
+  listSequences,
+  updateSequence,
+} from "../../sequence/store.js";
+import { BadRequestError, NotFoundError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+// ── Schemas ─────────────────────────────────────────────────────────
+
+const SequenceListParams = z
+  .object({
+    status: z.enum(["active", "paused", "archived"]).optional(),
+  })
+  .strict();
+
+const SequenceIdParams = z
+  .object({
+    id: z.string().min(1),
+  })
+  .strict();
+
+const CancelEnrollmentParams = z
+  .object({
+    enrollmentId: z.string().min(1),
+  })
+  .strict();
+
+const GuardrailSetParams = z
+  .object({
+    key: z.string().min(1),
+    value: z.string().min(1),
+  })
+  .strict();
+
+// ── Handlers ────────────────────────────────────────────────────────
+
+function handleSequenceList({ body = {} }: RouteHandlerArgs) {
+  getDb();
+  const { status } = SequenceListParams.parse(body);
+  const filter = status ? { status } : undefined;
+  const seqs = listSequences(filter);
+
+  const sequences = seqs.map((seq) => ({
+    ...seq,
+    activeEnrollments: countActiveEnrollments(seq.id),
+  }));
+
+  return { ok: true, sequences };
+}
+
+function handleSequenceGet({ body = {} }: RouteHandlerArgs) {
+  getDb();
+  const { id } = SequenceIdParams.parse(body);
+  const seq = getSequence(id);
+  if (!seq) throw new NotFoundError(`Sequence not found: ${id}`);
+
+  const enrollments = listEnrollments({ sequenceId: id });
+  const statusCounts = enrollments.reduce(
+    (acc, e) => {
+      acc[e.status] = (acc[e.status] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  return {
+    ok: true,
+    sequence: { ...seq, activeEnrollments: statusCounts["active"] ?? 0 },
+    enrollments: { total: enrollments.length, byStatus: statusCounts },
+  };
+}
+
+function handleSequencePause({ body = {} }: RouteHandlerArgs) {
+  getDb();
+  const { id } = SequenceIdParams.parse(body);
+  const seq = getSequence(id);
+  if (!seq) throw new NotFoundError(`Sequence not found: ${id}`);
+  if (seq.status === "paused") {
+    return { ok: true, message: "Sequence is already paused." };
+  }
+  updateSequence(id, { status: "paused" });
+  return { ok: true, message: `Sequence "${seq.name}" paused.` };
+}
+
+function handleSequenceResume({ body = {} }: RouteHandlerArgs) {
+  getDb();
+  const { id } = SequenceIdParams.parse(body);
+  const seq = getSequence(id);
+  if (!seq) throw new NotFoundError(`Sequence not found: ${id}`);
+  if (seq.status === "active") {
+    return { ok: true, message: "Sequence is already active." };
+  }
+  updateSequence(id, { status: "active" });
+  return { ok: true, message: `Sequence "${seq.name}" resumed.` };
+}
+
+function handleCancelEnrollment({ body = {} }: RouteHandlerArgs) {
+  getDb();
+  const { enrollmentId } = CancelEnrollmentParams.parse(body);
+  exitEnrollment(enrollmentId, "cancelled");
+  return { ok: true, message: `Enrollment ${enrollmentId} cancelled.` };
+}
+
+function handleSequenceStats() {
+  getDb();
+  const seqs = listSequences();
+  const activeSeqs = seqs.filter((s) => s.status === "active").length;
+  const allEnrollments = listEnrollments();
+  const activeEnrollments = allEnrollments.filter(
+    (e) => e.status === "active",
+  ).length;
+
+  return {
+    ok: true,
+    totalSequences: seqs.length,
+    activeSequences: activeSeqs,
+    totalEnrollments: allEnrollments.length,
+    activeEnrollments,
+  };
+}
+
+function handleGuardrailsShow() {
+  const cfg = getGuardrailConfig();
+  return { ok: true, config: cfg };
+}
+
+function handleGuardrailsSet({ body = {} }: RouteHandlerArgs) {
+  const { key, value } = GuardrailSetParams.parse(body);
+  const numVal = Number(value);
+  const boolVal =
+    value === "true" ? true : value === "false" ? false : undefined;
+
+  const patch: Partial<ReturnType<typeof getGuardrailConfig>> = {};
+  switch (key) {
+    case "dailySendCap":
+    case "daily_send_cap":
+      if (!Number.isFinite(numVal))
+        throw new BadRequestError(`Invalid numeric value for ${key}: ${value}`);
+      patch.dailySendCap = numVal;
+      break;
+    case "perSequenceHourlyRate":
+    case "hourly_rate":
+      if (!Number.isFinite(numVal))
+        throw new BadRequestError(`Invalid numeric value for ${key}: ${value}`);
+      patch.perSequenceHourlyRate = numVal;
+      break;
+    case "minimumStepDelaySec":
+    case "min_delay":
+      if (!Number.isFinite(numVal))
+        throw new BadRequestError(`Invalid numeric value for ${key}: ${value}`);
+      patch.minimumStepDelaySec = numVal;
+      break;
+    case "maxActiveEnrollments":
+    case "max_enrollments":
+      if (!Number.isFinite(numVal))
+        throw new BadRequestError(`Invalid numeric value for ${key}: ${value}`);
+      patch.maxActiveEnrollments = numVal;
+      break;
+    case "duplicateEnrollmentCheck":
+    case "duplicate_check":
+      if (boolVal === undefined)
+        throw new BadRequestError("Value must be true or false");
+      patch.duplicateEnrollmentCheck = boolVal;
+      break;
+    case "cooldownPeriodMs":
+      if (!Number.isFinite(numVal))
+        throw new BadRequestError(`Invalid numeric value for ${key}: ${value}`);
+      patch.cooldownPeriodMs = numVal;
+      break;
+    case "cooldown_days": {
+      if (!Number.isFinite(numVal))
+        throw new BadRequestError(`Invalid numeric value for ${key}: ${value}`);
+      patch.cooldownPeriodMs = numVal * 24 * 60 * 60 * 1000;
+      break;
+    }
+    default:
+      throw new BadRequestError(`Unknown guardrail key: ${key}`);
+  }
+
+  const updated = setGuardrailConfig(patch);
+  return { ok: true, message: `Updated ${key} = ${value}`, config: updated };
+}
+
+// ── Route definitions ───────────────────────────────────────────────
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "sequence_list",
+    method: "POST",
+    endpoint: "sequences/list",
+    handler: handleSequenceList,
+    summary: "List sequences",
+    description:
+      "List all sequences, optionally filtered by status (active, paused, archived).",
+    tags: ["sequences"],
+    requestBody: SequenceListParams,
+  },
+  {
+    operationId: "sequence_get",
+    method: "POST",
+    endpoint: "sequences/get",
+    handler: handleSequenceGet,
+    summary: "Get sequence details",
+    description:
+      "Get sequence details with enrollment stats, including step-by-step breakdown and enrollment status counts.",
+    tags: ["sequences"],
+    requestBody: SequenceIdParams,
+  },
+  {
+    operationId: "sequence_pause",
+    method: "POST",
+    endpoint: "sequences/pause",
+    handler: handleSequencePause,
+    summary: "Pause a sequence",
+    description:
+      "Pause a sequence, halting all scheduled step deliveries. No-op if already paused.",
+    tags: ["sequences"],
+    requestBody: SequenceIdParams,
+  },
+  {
+    operationId: "sequence_resume",
+    method: "POST",
+    endpoint: "sequences/resume",
+    handler: handleSequenceResume,
+    summary: "Resume a paused sequence",
+    description:
+      "Resume a paused sequence, re-enabling scheduled step deliveries. No-op if already active.",
+    tags: ["sequences"],
+    requestBody: SequenceIdParams,
+  },
+  {
+    operationId: "sequence_cancel_enrollment",
+    method: "POST",
+    endpoint: "sequences/cancel-enrollment",
+    handler: handleCancelEnrollment,
+    summary: "Cancel a specific enrollment",
+    description:
+      "Cancel a specific enrollment, stopping all future step deliveries for that contact.",
+    tags: ["sequences"],
+    requestBody: CancelEnrollmentParams,
+  },
+  {
+    operationId: "sequence_stats",
+    method: "GET",
+    endpoint: "sequences/stats",
+    handler: handleSequenceStats,
+    summary: "Overall sequence stats",
+    description:
+      "Returns aggregate statistics: total/active sequence counts and total/active enrollment counts.",
+    tags: ["sequences"],
+  },
+  {
+    operationId: "sequence_guardrails_show",
+    method: "GET",
+    endpoint: "sequences/guardrails",
+    handler: handleGuardrailsShow,
+    summary: "Show guardrail configuration",
+    description:
+      "Display the current guardrail configuration: daily send cap, hourly rate, step delay, max enrollments, duplicate check, and cooldown period.",
+    tags: ["sequences"],
+  },
+  {
+    operationId: "sequence_guardrails_set",
+    method: "POST",
+    endpoint: "sequences/guardrails",
+    handler: handleGuardrailsSet,
+    summary: "Update a guardrail setting",
+    description:
+      "Update a single guardrail setting by key. Valid keys: dailySendCap, perSequenceHourlyRate, minimumStepDelaySec, maxActiveEnrollments, duplicateEnrollmentCheck, cooldownPeriodMs, cooldown_days.",
+    tags: ["sequences"],
+    requestBody: GuardrailSetParams,
+  },
+];