@vellumai/assistant 0.8.7 → 0.8.8

package/src/runtime/routes/tool-call-confirmation-enrichment.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Tests for render-time enrichment of history tool calls with confirmation
+ * context: derived scope ladders for scope-aware tools and outstanding prompts
+ * read from the pending-interactions registry.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+
+import type { ConversationMessageToolCall } from "../../api/responses/conversation-message.js";
+import { clear, register } from "../pending-interactions.js";
+import {
+  collectPendingConfirmations,
+  enrichToolCallsWithConfirmation,
+} from "./tool-call-confirmation-enrichment.js";
+
+const WORKSPACE = "/home/user/project";
+
+function toolCall(
+  overrides: Partial<ConversationMessageToolCall>,
+): ConversationMessageToolCall {
+  return {
+    name: "file_read",
+    input: {},
+    ...overrides,
+  };
+}
+
+afterEach(() => {
+  clear();
+});
+
+describe("collectPendingConfirmations", () => {
+  test("keys confirmation interactions by toolUseId", () => {
+    // GIVEN a confirmation interaction registered for a conversation with a
+    // tool-use id and confirmation details
+    register("req-1", {
+      conversationId: "conv-1",
+      kind: "confirmation",
+      toolUseId: "tool-abc",
+      confirmationDetails: {
+        toolName: "file_read",
+        input: { path: "/home/user/project/a.txt" },
+        riskLevel: "low",
+        allowlistOptions: [],
+        scopeOptions: [],
+      },
+    });
+
+    // WHEN we collect the conversation's pending confirmations
+    const byToolUseId = collectPendingConfirmations("conv-1");
+
+    // THEN the interaction is keyed by its tool-use id
+    expect(byToolUseId.size).toBe(1);
+    expect(byToolUseId.get("tool-abc")?.requestId).toBe("req-1");
+  });
+
+  test("ignores interactions lacking a toolUseId or confirmation details", () => {
+    // GIVEN a confirmation without a toolUseId AND a non-confirmation
+    // interaction in the same conversation
+    register("req-no-tool", {
+      conversationId: "conv-2",
+      kind: "confirmation",
+      confirmationDetails: {
+        toolName: "file_read",
+        input: {},
+        riskLevel: "low",
+        allowlistOptions: [],
+        scopeOptions: [],
+      },
+    });
+    register("req-secret", {
+      conversationId: "conv-2",
+      kind: "secret",
+      toolUseId: "tool-xyz",
+    });
+
+    // WHEN we collect the conversation's pending confirmations
+    const byToolUseId = collectPendingConfirmations("conv-2");
+
+    // THEN neither is included — one has no toolUseId, the other is not a
+    // confirmation
+    expect(byToolUseId.size).toBe(0);
+  });
+});
+
+describe("enrichToolCallsWithConfirmation", () => {
+  test("derives the scope ladder for scope-aware tools", () => {
+    // GIVEN a completed scope-aware tool call with no registry entry
+    const calls = [toolCall({ id: "tool-1", name: "file_read" })];
+
+    // WHEN we enrich it
+    const [enriched] = enrichToolCallsWithConfirmation(calls, {
+      workspaceDir: WORKSPACE,
+      pendingConfirmations: new Map(),
+    });
+
+    // THEN the scope ladder is derived from the workspace and tool name
+    expect(enriched?.scopeOptions?.[0]).toEqual({
+      label: WORKSPACE,
+      scope: WORKSPACE,
+    });
+    // AND no pending confirmation is stamped
+    expect(enriched?.pendingConfirmation).toBeUndefined();
+  });
+
+  test("leaves non-scope-aware tool calls untouched", () => {
+    // GIVEN a tool call for a tool that has no scope ladder
+    const original = toolCall({ id: "tool-2", name: "web_search" });
+
+    // WHEN we enrich it with no matching registry entry
+    const [enriched] = enrichToolCallsWithConfirmation([original], {
+      workspaceDir: WORKSPACE,
+      pendingConfirmations: new Map(),
+    });
+
+    // THEN the tool call is returned unchanged (same reference)
+    expect(enriched).toBe(original);
+  });
+
+  test("stamps the pending confirmation when the registry has a match", () => {
+    // GIVEN a registry entry matching the tool call by id
+    const pendingConfirmations = collectPendingConfirmationsFixture();
+    const calls = [toolCall({ id: "tool-abc", name: "file_read" })];
+
+    // WHEN we enrich it
+    const [enriched] = enrichToolCallsWithConfirmation(calls, {
+      workspaceDir: WORKSPACE,
+      pendingConfirmations,
+    });
+
+    // THEN the outstanding prompt is projected onto the tool call
+    expect(enriched?.pendingConfirmation?.requestId).toBe("req-1");
+    expect(enriched?.pendingConfirmation?.toolName).toBe("file_read");
+    expect(enriched?.pendingConfirmation?.riskLevel).toBe("high");
+    // AND the directory scope ladder carries through from the registry so a
+    // restored prompt offers the same scope the live event did
+    expect(enriched?.pendingConfirmation?.directoryScopeOptions).toEqual([
+      { label: "Anywhere in project/", scope: "/home/user/project" },
+    ]);
+    // AND the derived scope ladder is still present
+    expect(enriched?.scopeOptions?.length).toBeGreaterThan(0);
+  });
+});
+
+function collectPendingConfirmationsFixture() {
+  register("req-1", {
+    conversationId: "conv-fixture",
+    kind: "confirmation",
+    toolUseId: "tool-abc",
+    confirmationDetails: {
+      toolName: "file_read",
+      input: { path: "/home/user/project/a.txt" },
+      riskLevel: "high",
+      allowlistOptions: [],
+      scopeOptions: [],
+      directoryScopeOptions: [
+        { label: "Anywhere in project/", scope: "/home/user/project" },
+      ],
+    },
+  });
+  return collectPendingConfirmations("conv-fixture");
+}

package/src/runtime/routes/tool-call-confirmation-enrichment.ts

@@ -0,0 +1,107 @@
+/**
+ * Render-time enrichment of history tool calls with confirmation context.
+ *
+ * Two pieces of state the persisted content does not itself carry are layered
+ * onto each rendered tool call here so the web/API clients can render the same
+ * confirmation UI on a cold reconnect (or a history reopen after the live
+ * event buffer has aged out) that the live `confirmation_request` SSE stream
+ * would have produced:
+ *
+ * 1. `scopeOptions` — the confirmation scope ladder for scope-aware tools
+ *    (file/bash). It is a pure function of the workspace directory and the
+ *    tool name, so it is *derived* at render rather than persisted. Completed
+ *    tool calls regain the ladder the rule editor's trust-rule suggestion
+ *    fallback consumes.
+ *
+ * 2. `pendingConfirmation` — the in-flight prompt for a tool call still
+ *    awaiting a user decision. It is read from the in-memory
+ *    `pending-interactions` registry (the authoritative store of unresolved
+ *    prompts), so it appears only while the prompt is genuinely outstanding.
+ */
+
+import type { ConversationMessageToolCall } from "../../api/responses/conversation-message.js";
+import { generateScopeOptions } from "../../permissions/checker.js";
+import {
+  type ConfirmationDetails,
+  getByConversation,
+} from "../pending-interactions.js";
+
+/** A pending confirmation matched to the tool call it prompts for, keyed by `toolUseId`. */
+interface PendingConfirmationMatch {
+  requestId: string;
+  details: ConfirmationDetails;
+}
+
+/**
+ * Build the `toolUseId → pending confirmation` lookup for a conversation from
+ * the registry. Only confirmation interactions that carry both a `toolUseId`
+ * and `confirmationDetails` can be stamped onto a wire tool call.
+ */
+export function collectPendingConfirmations(
+  conversationId: string,
+): Map<string, PendingConfirmationMatch> {
+  const byToolUseId = new Map<string, PendingConfirmationMatch>();
+  for (const interaction of getByConversation(conversationId)) {
+    if (
+      interaction.kind === "confirmation" &&
+      interaction.confirmationDetails &&
+      interaction.toolUseId
+    ) {
+      byToolUseId.set(interaction.toolUseId, {
+        requestId: interaction.requestId,
+        details: interaction.confirmationDetails,
+      });
+    }
+  }
+  return byToolUseId;
+}
+
+/** Project a registry `ConfirmationDetails` into the wire `pendingConfirmation` shape. */
+function toPendingConfirmation(
+  requestId: string,
+  details: ConfirmationDetails,
+): NonNullable<ConversationMessageToolCall["pendingConfirmation"]> {
+  return {
+    requestId,
+    toolName: details.toolName,
+    riskLevel: details.riskLevel,
+    input: details.input,
+    allowlistOptions: details.allowlistOptions,
+    scopeOptions: details.scopeOptions,
+    directoryScopeOptions: details.directoryScopeOptions,
+    persistentDecisionsAllowed: details.persistentDecisionsAllowed,
+  };
+}
+
+/**
+ * Layer derived `scopeOptions` and any outstanding `pendingConfirmation` onto a
+ * message's rendered tool calls. Returns a new array; tool calls without
+ * enrichment are returned unchanged.
+ */
+export function enrichToolCallsWithConfirmation(
+  toolCalls: ConversationMessageToolCall[],
+  opts: {
+    workspaceDir: string;
+    pendingConfirmations: ReadonlyMap<string, PendingConfirmationMatch>;
+  },
+): ConversationMessageToolCall[] {
+  return toolCalls.map((tc) => {
+    const scopeOptions = generateScopeOptions(opts.workspaceDir, tc.name);
+    const match = tc.id ? opts.pendingConfirmations.get(tc.id) : undefined;
+    if (scopeOptions.length === 0 && !match) {
+      return tc;
+    }
+    return {
+      ...tc,
+      ...(scopeOptions.length > 0 ? { scopeOptions } : {}),
+      ...(match
+        ? {
+            pendingConfirmation: toPendingConfirmation(
+              match.requestId,
+              match.details,
+            ),
+          }
+        : {}),
+    };
+  });
+}

package/src/runtime/routes/trust-rules-routes.ts

@@ -43,9 +43,30 @@ const TrustRulesListParams = z
   })
   .strict();
 
+const TrustRuleSchema = z.object({
+  id: z.string(),
+  tool: z.string(),
+  pattern: z.string(),
+  risk: z.enum(["low", "medium", "high"]),
+  description: z.string(),
+  origin: z.enum(["default", "user_defined"]),
+  userModified: z.boolean(),
+  deleted: z.boolean(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+const TrustRulesListResponseSchema = z.object({
+  rules: z.array(TrustRuleSchema),
+});
+type TrustRulesListResponse = z.infer<typeof TrustRulesListResponseSchema>;
+
 // ── Handlers ────────────────────────────────────────────────────────────
 
-async function handleList({ queryParams = {}, body = {} }: RouteHandlerArgs) {
+async function handleList({
+  queryParams = {},
+  body = {},
+}: RouteHandlerArgs): Promise<TrustRulesListResponse> {
   // HTTP GET delivers filters via queryParams; CLI IPC puts them in body.
   const source = Object.keys(queryParams).length > 0 ? queryParams : body;
   const p = TrustRulesListParams.parse(source);
@@ -54,7 +75,9 @@ async function handleList({ queryParams = {}, body = {} }: RouteHandlerArgs) {
   if (p.origin) qs.set("origin", p.origin);
   if (p.include_all) qs.set("include_all", "true");
   const query = qs.toString();
-  return gatewayFetch(`/v1/trust-rules${query ? `?${query}` : ""}`);
+  return gatewayFetch(
+    `/v1/trust-rules${query ? `?${query}` : ""}`,
+  ) as Promise<TrustRulesListResponse>;
 }
 
 // ── Route definitions ───────────────────────────────────────────────────
@@ -73,6 +96,7 @@ export const ROUTES: RouteDefinition[] = [
     description:
       "List trust rules, optionally filtered by tool, origin, or include_all.",
     tags: ["trust-rules"],
+    responseBody: TrustRulesListResponseSchema,
     queryParams: [
       { name: "tool", description: "Filter by tool name" },
       { name: "origin", description: "Filter by origin" },

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

@@ -15,6 +15,7 @@ import { sanitizeForTts } from "../../calls/tts-text-sanitizer.js";
 import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import { getConfig } from "../../config/loader.js";
 import { getMessageContent } from "../../daemon/handlers/conversation-history.js";
+import { listCatalogProvidersForDisplay } from "../../tts/provider-catalog.js";
 import {
   synthesizeText,
   TtsSynthesisError,
@@ -136,6 +137,10 @@ const ttsResponseHeaders = () => ({
 // Handlers
 // ---------------------------------------------------------------------------
 
+function handleListTtsProviders() {
+  return { providers: listCatalogProvidersForDisplay() };
+}
+
 async function handleMessageTts({ pathParams, queryParams }: RouteHandlerArgs) {
   const config = getConfig();
 
@@ -226,6 +231,36 @@ async function handleSynthesizeCliTts({ body }: RouteHandlerArgs) {
 // ---------------------------------------------------------------------------
 
 export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "tts_providers",
+    endpoint: "tts/providers",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "List TTS providers",
+    description:
+      "Return the catalog of available TTS providers with client-facing metadata.",
+    tags: ["tts"],
+    responseBody: z.object({
+      providers: z.array(
+        z.object({
+          id: z.string(),
+          displayName: z.string(),
+          subtitle: z.string(),
+          supportsVoiceSelection: z.boolean(),
+          apiKeyPlaceholder: z.string(),
+          credentialsGuide: z.object({
+            description: z.string(),
+            url: z.string(),
+            linkLabel: z.string(),
+          }),
+        }),
+      ),
+    }),
+    handler: handleListTtsProviders,
+  },
   {
     operationId: "messages_tts",
     endpoint: "messages/:messageId/tts",

package/src/runtime/routes/types.ts

@@ -31,6 +31,70 @@ export interface RoutePathParam {
   description?: string;
 }
 
+/**
+ * Content types a route can declare a request body for. `application/json`
+ * is the implicit default when `requestBody` is a bare Zod schema, so it is
+ * only spelled out here for the explicit `{ contentType, schema }` form.
+ */
+export type RouteRequestContentType =
+  | "application/json"
+  | "application/octet-stream"
+  | "multipart/form-data";
+
+/**
+ * A route's request body. Either:
+ * - a bare Zod schema, which is advertised as `application/json`, or
+ * - an explicit `{ contentType, schema }` pair for non-JSON bodies (e.g. a
+ *   raw `application/octet-stream` upload). `schema` may be a Zod schema or a
+ *   plain JSON Schema fragment (e.g. `{ type: "string", format: "binary" }`).
+ *
+ * The OpenAPI generator turns this into the operation's `requestBody`, so the
+ * generated client SDK describes a real body type instead of `never`. The HTTP
+ * adapter parses the body off the request `Content-Type` header, so this field
+ * is a codegen signal only and does not change runtime request handling.
+ */
+export type RouteRequestBody =
+  | z.ZodType
+  | {
+      contentType: RouteRequestContentType;
+      schema: z.ZodType | Record<string, unknown>;
+    };
+
+/**
+ * Content types a route can declare a success response body for.
+ * `application/json` is the implicit default when `responseBody` is a bare
+ * Zod schema, so it is only spelled out here for the explicit
+ * `{ contentType, schema }` form (e.g. a binary `application/octet-stream`
+ * download or an `application/gzip` archive).
+ */
+export type RouteResponseContentType =
+  | "application/json"
+  | "application/octet-stream"
+  | "application/gzip"
+  | "application/pdf"
+  | "application/zip";
+
+/**
+ * A route's success response body. Either:
+ * - a bare Zod schema, which is advertised as `application/json`, or
+ * - an explicit `{ contentType, schema }` pair for non-JSON responses (e.g. a
+ *   binary download). `schema` may be a Zod schema or a plain JSON Schema
+ *   fragment (e.g. `{ type: "string", format: "binary" }`, which is not
+ *   expressible as a bare Zod type).
+ *
+ * The OpenAPI generator turns this into the operation's success response, so
+ * the generated client SDK describes a real response type (e.g. `Blob`)
+ * instead of `unknown`. Handlers serialize their own bytes via `RouteResponse`,
+ * so this field is a codegen signal only and does not change runtime
+ * response handling.
+ */
+export type RouteResponseBody =
+  | z.ZodType
+  | {
+      contentType: RouteResponseContentType;
+      schema: z.ZodType | Record<string, unknown>;
+    };
+
 export interface RouteHandlerArgs {
   pathParams?: Record<string, string>;
   queryParams?: Record<string, string>;
@@ -102,8 +166,8 @@ export interface RouteDefinition {
   tags?: string[];
   pathParams?: RoutePathParam[];
   queryParams?: RouteQueryParam[];
-  requestBody?: z.ZodType;
-  responseBody?: z.ZodType;
+  requestBody?: RouteRequestBody;
+  responseBody?: RouteResponseBody;
   /**
    * HTTP status code for the success response. Defaults to "200".
    * Use "201" for resource creation, "204" for no-content responses.
@@ -145,12 +209,6 @@ export interface RouteDefinition {
    * RouteError subclasses rather than explicit Response objects.
    */
   additionalResponses?: Record<string, { description: string }>;
-  /**
-   * When true, the route expects a raw binary body (e.g. file uploads).
-   * The HTTP adapter already reads `rawBody` for non-JSON content types;
-   * this flag is a declarative signal for documentation and tooling.
-   */
-  rawBody?: boolean;
   /**
    * Per-route request-log control. Routes that opt in can suppress the
    * per-request INFO log line after a confirmed run of successful

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

@@ -1,10 +1,10 @@
 /**
  * Route handlers for usage and cost summary endpoints.
  *
- * GET /v1/usage/totals?from=&to=              — aggregate totals for a time range
- * GET /v1/usage/daily?from=&to=               — per-day buckets for a time range
- * GET /v1/usage/breakdown?from=&to=&groupBy=  — grouped breakdown
- * GET /v1/usage/series?from=&to=&granularity=&groupBy= — grouped time-series buckets
+ * GET /v1/usage/totals?from=&to=&scheduleId=  — aggregate totals for a time range
+ * GET /v1/usage/daily?from=&to=&scheduleId=   — per-day buckets for a time range
+ * GET /v1/usage/breakdown?from=&to=&groupBy=&scheduleId=  — grouped breakdown
+ * GET /v1/usage/series?from=&to=&granularity=&groupBy=&scheduleId= — grouped time-series buckets
  */
 
 import { z } from "zod";
@@ -18,10 +18,12 @@ import {
   type GroupByDimension,
   USAGE_GROUP_BY_DIMENSIONS,
   USAGE_SERIES_GROUP_BY_DIMENSIONS,
+  type UsageAggregationFilter,
   type UsageGranularity,
 } from "../../memory/llm-usage-store.js";
 import { validateTimezone } from "../../memory/usage-buckets.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import { parseEpochMillisRange } from "./epoch-millis-range.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -29,6 +31,8 @@ const VALID_GROUP_BY = new Set<string>(USAGE_GROUP_BY_DIMENSIONS);
 const VALID_SERIES_GROUP_BY = new Set<string>(USAGE_SERIES_GROUP_BY_DIMENSIONS);
 const GROUP_BY_DESCRIPTION = USAGE_GROUP_BY_DIMENSIONS.join(", ");
 const SERIES_GROUP_BY_DESCRIPTION = USAGE_SERIES_GROUP_BY_DIMENSIONS.join(", ");
+const SCHEDULE_ID_FILTER_DESCRIPTION =
+  "Optional schedule id. When set, usage is attributed by cron run windows for that schedule.";
 
 const usageTotalsSchema = z.object({
   totalInputTokens: z.number(),
@@ -86,43 +90,23 @@ function resolveTimezone(queryParams: Record<string, string>): string {
   return tz;
 }
 
-function parseTimeRange(queryParams: Record<string, string>): {
-  from: number;
-  to: number;
-} {
-  const fromRaw = queryParams.from;
-  const toRaw = queryParams.to;
-
-  if (!fromRaw || !toRaw) {
-    throw new BadRequestError(
-      'Missing required query parameters: "from" and "to" (epoch milliseconds)',
-    );
-  }
-
-  const from = Number(fromRaw);
-  const to = Number(toRaw);
-
-  if (!Number.isFinite(from) || !Number.isFinite(to)) {
-    throw new BadRequestError(
-      '"from" and "to" must be valid numbers (epoch milliseconds)',
-    );
-  }
-
-  if (from > to) {
-    throw new BadRequestError('"from" must be less than or equal to "to"');
-  }
-
-  return { from, to };
+function parseUsageAggregationFilter(
+  queryParams: Record<string, string>,
+): UsageAggregationFilter {
+  const scheduleId = queryParams.scheduleId?.trim();
+  return scheduleId ? { scheduleId } : {};
 }
 
 function handleUsageTotals({ queryParams }: RouteHandlerArgs) {
-  const range = parseTimeRange(queryParams ?? {});
-  return getUsageTotals(range);
+  const qp = queryParams ?? {};
+  const range = parseEpochMillisRange(qp);
+  const filter = parseUsageAggregationFilter(qp);
+  return getUsageTotals(range, filter);
 }
 
 function handleUsageDaily({ queryParams }: RouteHandlerArgs) {
   const qp = queryParams ?? {};
-  const range = parseTimeRange(qp);
+  const range = parseEpochMillisRange(qp);
   const granularity = qp.granularity ?? "daily";
   if (granularity !== "daily" && granularity !== "hourly") {
     throw new BadRequestError(
@@ -130,16 +114,17 @@ function handleUsageDaily({ queryParams }: RouteHandlerArgs) {
     );
   }
   const tz = resolveTimezone(qp);
+  const filter = parseUsageAggregationFilter(qp);
   const buckets =
     granularity === "hourly"
-      ? getUsageHourBuckets(range, tz, { fillEmpty: true })
-      : getUsageDayBuckets(range, tz, { fillEmpty: true });
+      ? getUsageHourBuckets(range, tz, { fillEmpty: true }, filter)
+      : getUsageDayBuckets(range, tz, { fillEmpty: true }, filter);
   return { buckets };
 }
 
 function handleUsageBreakdown({ queryParams }: RouteHandlerArgs) {
   const qp = queryParams ?? {};
-  const range = parseTimeRange(qp);
+  const range = parseEpochMillisRange(qp);
 
   const groupBy = qp.groupBy;
   if (!groupBy) {
@@ -153,13 +138,18 @@ function handleUsageBreakdown({ queryParams }: RouteHandlerArgs) {
     );
   }
 
-  const breakdown = getUsageGroupBreakdown(range, groupBy as GroupByDimension);
+  const filter = parseUsageAggregationFilter(qp);
+  const breakdown = getUsageGroupBreakdown(
+    range,
+    groupBy as GroupByDimension,
+    filter,
+  );
   return { breakdown };
 }
 
 function handleUsageSeries({ queryParams }: RouteHandlerArgs) {
   const qp = queryParams ?? {};
-  const range = parseTimeRange(qp);
+  const range = parseEpochMillisRange(qp);
   const granularity = qp.granularity ?? "daily";
   if (granularity !== "daily" && granularity !== "hourly") {
     throw new BadRequestError(
@@ -180,12 +170,14 @@ function handleUsageSeries({ queryParams }: RouteHandlerArgs) {
   }
 
   const tz = resolveTimezone(qp);
+  const filter = parseUsageAggregationFilter(qp);
   const buckets = getUsageGroupedSeries(
     range,
     groupBy as Exclude<GroupByDimension, "conversation">,
     granularity as UsageGranularity,
     tz,
     { fillEmpty: true },
+    filter,
   );
   return { buckets };
 }
@@ -213,6 +205,10 @@ export const ROUTES: RouteDefinition[] = [
         type: "integer",
         description: "End epoch millis (required)",
       },
+      {
+        name: "scheduleId",
+        description: SCHEDULE_ID_FILTER_DESCRIPTION,
+      },
     ],
     responseBody: usageTotalsSchema,
     handler: handleUsageTotals,
@@ -249,6 +245,10 @@ export const ROUTES: RouteDefinition[] = [
         description:
           'IANA timezone identifier (e.g. "America/Los_Angeles"). Bucket boundaries and display labels are computed in this timezone. Defaults to "UTC" for backwards compatibility.',
       },
+      {
+        name: "scheduleId",
+        description: SCHEDULE_ID_FILTER_DESCRIPTION,
+      },
     ],
     responseBody: z.object({
       buckets: z.array(usageDayBucketSchema).describe("Usage bucket objects"),
@@ -282,6 +282,10 @@ export const ROUTES: RouteDefinition[] = [
         name: "groupBy",
         description: `Group by: ${GROUP_BY_DESCRIPTION} (required)`,
       },
+      {
+        name: "scheduleId",
+        description: SCHEDULE_ID_FILTER_DESCRIPTION,
+      },
     ],
     responseBody: z.object({
       breakdown: z
@@ -327,6 +331,10 @@ export const ROUTES: RouteDefinition[] = [
         description:
           'IANA timezone identifier (e.g. "America/Los_Angeles"). Bucket boundaries and display labels are computed in this timezone. Defaults to "UTC".',
       },
+      {
+        name: "scheduleId",
+        description: SCHEDULE_ID_FILTER_DESCRIPTION,
+      },
     ],
     responseBody: z.object({
       buckets: z