@vellumai/assistant 0.8.1 → 0.8.3

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

@@ -78,7 +78,8 @@ function handleCreateSchedule(body: Record<string, unknown>) {
   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 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";
@@ -298,16 +299,12 @@ export const ROUTES: RouteDefinition[] = [
         .boolean()
         .describe("Whether the schedule starts active (default true)")
         .optional(),
-      mode: z
-        .string()
-        .describe("Currently must be 'execute'")
-        .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 ?? {}),
+    handler: ({ body }: RouteHandlerArgs) => handleCreateSchedule(body ?? {}),
   },
   {
     operationId: "listScheduleRuns",

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

@@ -11,6 +11,7 @@ import {
   getMessages,
   type MessageRow,
 } from "../../memory/conversation-crud.js";
+import { getConversationUsageTotals } from "../../memory/llm-usage-store.js";
 import { getSubagentManager } from "../../subagent/index.js";
 import { getLogger } from "../../util/logger.js";
 import { BadRequestError, NotFoundError } from "./errors.js";
@@ -29,6 +30,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 export interface SubagentDetailResult {
   subagentId: string;
   objective?: string;
+  usage?: { inputTokens: number; outputTokens: number; estimatedCost: number };
   events: Array<{
     type: string;
     content: string;
@@ -94,7 +96,11 @@ export function parseSubagentMessages(
         typeof block.text === "string"
       ) {
         events.push({ type: "text", content: block.text, messageId: m.id });
-      } else if (block.type === "tool_use") {
+      } else if (
+        block.type === "tool_use" ||
+        block.type === "server_tool_use" ||
+        block.type === "mcp_tool_use"
+      ) {
         const name = typeof block.name === "string" ? block.name : "unknown";
         const input = isRecord(block.input)
           ? (block.input as Record<string, unknown>)
@@ -106,7 +112,11 @@ export function parseSubagentMessages(
           toolName: name,
         });
         if (id) pendingTools.set(id, name);
-      } else if (block.type === "tool_result") {
+      } else if (
+        block.type === "tool_result" ||
+        block.type === "web_search_tool_result" ||
+        block.type === "mcp_tool_result"
+      ) {
         const toolUseId =
           typeof block.tool_use_id === "string" ? block.tool_use_id : "";
         const resultContent =
@@ -114,13 +124,18 @@ export function parseSubagentMessages(
             ? block.content
             : Array.isArray(block.content)
               ? (block.content as unknown[])
-                  .filter(
-                    (b): b is Record<string, unknown> =>
-                      isRecord(b) &&
-                      (b as Record<string, unknown>).type === "text" &&
-                      typeof (b as Record<string, unknown>).text === "string",
-                  )
-                  .map((b) => b.text as string)
+                  .filter((b): b is Record<string, unknown> => isRecord(b))
+                  .map((b) => {
+                    if (b.type === "text" && typeof b.text === "string")
+                      return b.text;
+                    if (
+                      b.type === "web_search_result" &&
+                      typeof b.title === "string"
+                    )
+                      return `${b.title}\n${typeof b.url === "string" ? b.url : ""}`;
+                    return null;
+                  })
+                  .filter((s): s is string => s != null)
                   .join("\n")
               : "";
         const isError = block.is_error === true;
@@ -142,7 +157,30 @@ function getSubagentDetail(
   subagentId: string,
   conversationId: string,
 ): SubagentDetailResult {
-  return parseSubagentMessages(subagentId, getMessages(conversationId));
+  const messages = getMessages(conversationId);
+  log.info(
+    {
+      subagentId,
+      conversationId,
+      messageCount: messages.length,
+      roles: messages.map((m) => m.role),
+    },
+    "getSubagentDetail: raw messages from DB",
+  );
+  const result = parseSubagentMessages(subagentId, messages);
+  log.info(
+    {
+      subagentId,
+      eventCount: result.events.length,
+      eventTypes: result.events.map((e) => `${e.type}:${e.toolName ?? ""}`),
+    },
+    "getSubagentDetail: parsed events",
+  );
+  const usage = getConversationUsageTotals(conversationId);
+  if (usage.inputTokens > 0 || usage.outputTokens > 0) {
+    result.usage = usage;
+  }
+  return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -150,6 +188,47 @@ function getSubagentDetail(
 // ---------------------------------------------------------------------------
 
 export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "reconcileSubagents",
+    endpoint: "subagents/reconcile",
+    method: "GET",
+    policyKey: "subagents",
+    summary: "Reconcile subagent live status",
+    description:
+      "Returns the live in-memory status of all subagents known to the daemon for a given parent conversation. Subagents not in the response are orphaned.",
+    tags: ["subagents"],
+    queryParams: [
+      {
+        name: "parentConversationId",
+        schema: { type: "string" },
+        description: "Parent conversation ID",
+      },
+    ],
+    responseBody: z.object({
+      subagents: z.record(
+        z.string(),
+        z.object({
+          status: z.string(),
+        }),
+      ),
+    }),
+    handler: ({ queryParams }) => {
+      const parentConversationId = queryParams?.parentConversationId;
+      if (!parentConversationId) {
+        throw new BadRequestError(
+          "parentConversationId query parameter is required",
+        );
+      }
+      const manager = getSubagentManager();
+      const children = manager.getChildrenOf(parentConversationId);
+      const subagents: Record<string, { status: string }> = {};
+      for (const child of children) {
+        subagents[child.config.id] = { status: child.status };
+      }
+      return { subagents };
+    },
+  },
+
   {
     operationId: "getSubagentDetail",
     endpoint: "subagents/:id",
@@ -168,14 +247,19 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({
       subagentId: z.string(),
       objective: z.string(),
+      usage: z
+        .object({
+          inputTokens: z.number(),
+          outputTokens: z.number(),
+          estimatedCost: z.number(),
+        })
+        .optional(),
       events: z.array(z.unknown()).describe("Subagent event objects"),
     }),
     handler: ({ pathParams, queryParams }) => {
       const conversationId = queryParams?.conversationId;
       if (!conversationId) {
-        throw new BadRequestError(
-          "conversationId query parameter is required",
-        );
+        throw new BadRequestError("conversationId query parameter is required");
       }
 
       const manager = getSubagentManager();
@@ -209,11 +293,7 @@ export const ROUTES: RouteDefinition[] = [
       }
 
       const manager = getSubagentManager();
-      const aborted = manager.abort(
-        pathParams!.id,
-        () => {},
-        conversationId,
-      );
+      const aborted = manager.abort(pathParams!.id, () => {}, conversationId);
 
       if (!aborted) {
         log.warn(

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

@@ -7,6 +7,7 @@
 import { z } from "zod";
 
 import { recordLifecycleEvent } from "../../memory/lifecycle-events-store.js";
+import { getUsageTelemetryReporter } from "../../telemetry/usage-telemetry-reporter.js";
 import { getLogger } from "../../util/logger.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -32,6 +33,15 @@ function handleRecordLifecycleEvent({ body }: RouteHandlerArgs) {
   return { id: event.id, event_name: event.eventName };
 }
 
+async function handleTelemetryFlush() {
+  const reporter = getUsageTelemetryReporter();
+  if (!reporter) {
+    return { flushed: false, reason: "disabled" };
+  }
+  await reporter.flush();
+  return { flushed: true };
+}
+
 export const ROUTES: RouteDefinition[] = [
   {
     operationId: "telemetry_lifecycle",
@@ -58,4 +68,21 @@ export const ROUTES: RouteDefinition[] = [
     ]),
     handler: handleRecordLifecycleEvent,
   },
+  {
+    operationId: "telemetry_flush",
+    endpoint: "telemetry/flush",
+    method: "POST",
+    summary: "Flush pending telemetry events",
+    description:
+      "Force-flush all pending usage, turn, and lifecycle telemetry events to the platform.",
+    tags: ["telemetry"],
+    responseBody: z.union([
+      z.object({ flushed: z.literal(true) }),
+      z.object({
+        flushed: z.literal(false),
+        reason: z.string(),
+      }),
+    ]),
+    handler: handleTelemetryFlush,
+  },
 ];

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

@@ -94,10 +94,35 @@ async function doSynthesize(
       throw new ServiceUnavailableError("TTS provider is not configured");
     }
 
-    throw new BadGatewayError("TTS synthesis failed");
+    throw new BadGatewayError(formatTtsFailureMessage(err));
   }
 }
 
+/**
+ * Build a user-facing error message for a failed TTS synthesis, embedding the
+ * upstream provider's message when available.
+ *
+ * The provider adapters surface a clean upstream message (e.g. "Free users
+ * cannot use library voices via the API…") and `synthesize-text` already
+ * prefixes those with `"TTS synthesis failed (provider: <id>): "`. We pass
+ * pre-prefixed messages through verbatim and only add the base prefix for
+ * raw provider errors, so users never see double- or triple-prefixed
+ * messages on the desktop / channels.
+ *
+ * Exported for unit testing.
+ */
+export function formatTtsFailureMessage(err: unknown): string {
+  const base = "TTS synthesis failed";
+  if (err instanceof Error && err.message && err.message.trim()) {
+    const trimmed = err.message.trim();
+    if (/^TTS synthesis failed\b/i.test(trimmed)) {
+      return trimmed;
+    }
+    return `${base}: ${trimmed}`;
+  }
+  return base;
+}
+
 // ---------------------------------------------------------------------------
 // Response headers — shared by both routes
 // ---------------------------------------------------------------------------
@@ -191,7 +216,7 @@ async function handleSynthesizeCliTts({ body }: RouteHandlerArgs) {
       throw new ServiceUnavailableError("TTS provider is not configured");
     }
 
-    throw new BadGatewayError("TTS synthesis failed");
+    throw new BadGatewayError(formatTtsFailureMessage(err));
   }
 }
 

package/src/runtime/routes/workspace-routes.test.ts

@@ -9,6 +9,10 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { beforeAll, describe, expect, test } from "bun:test";
 
+import { SYNC_TAGS } from "../../daemon/message-types/sync.js";
+import type { AssistantEvent } from "../assistant-event.js";
+import { assistantEventHub } from "../assistant-event-hub.js";
+
 // ---------------------------------------------------------------------------
 // Create a temp workspace directory for isolation
 // ---------------------------------------------------------------------------
@@ -59,6 +63,15 @@ function getRoute(operationId: string): RouteDefinition {
   return route;
 }
 
+async function waitFor(predicate: () => boolean): Promise<void> {
+  const deadline = Date.now() + 500;
+  while (Date.now() < deadline) {
+    if (predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+  throw new Error("Timed out waiting for workspace route event");
+}
+
 // ===========================================================================
 // resolveWorkspacePath
 // ===========================================================================
@@ -492,6 +505,36 @@ describe("POST /v1/workspace/write", () => {
       handler({ body: { path: "subdir", content: "should fail" } }),
     ).toThrow(ConflictError);
   });
+
+  test("publishes sounds sync events when writing sounds config", async () => {
+    const received: AssistantEvent[] = [];
+    const subscription = assistantEventHub.subscribe({
+      type: "process",
+      callback: (event) => {
+        received.push(event);
+      },
+    });
+
+    try {
+      handler({
+        body: {
+          path: "data/sounds/config.json",
+          content: "{}",
+        },
+      });
+      await waitFor(() => received.length === 2);
+      expect(received.map((event) => event.message.type)).toEqual([
+        "sounds_config_updated",
+        "sync_changed",
+      ]);
+      expect(received[1]!.message).toEqual({
+        type: "sync_changed",
+        tags: [SYNC_TAGS.assistantSounds],
+      });
+    } finally {
+      subscription.dispose();
+    }
+  });
 });
 
 // ===========================================================================