@vellumai/assistant 0.8.5 → 0.8.7

package/src/runtime/routes/types.ts

@@ -4,6 +4,8 @@
 
 import type { z } from "zod";
 
+import type { RoutePolicy } from "../auth/route-policy.js";
+
 export interface RouteQueryParam {
   name: string;
   type?: string;
@@ -79,8 +81,22 @@ export interface RouteDefinition {
   operationId: string;
   endpoint: string;
   method: string;
+  /**
+   * Scope + principal-type policy for this route.
+   *
+   * `null` means the route is intentionally unprotected — health
+   * probes, public capability-token endpoints, and the like.
+   *
+   * A `RoutePolicy` object declares the scopes a caller must hold
+   * and which principal types are allowed. Both the HTTP server
+   * (`enforcePolicy()`) and the gateway IPC proxy (via the route
+   * schema served from `get_route_schema`) read this field.
+   *
+   * Required so the type system catches every new route — there is
+   * no separate registry to forget to update.
+   */
+  policy: RoutePolicy | null;
   handler: (args: RouteHandlerArgs) => unknown | Promise<unknown>;
-  policyKey?: string;
   summary?: string;
   description?: string;
   tags?: string[];
@@ -112,13 +128,6 @@ export interface RouteDefinition {
    * will be served directly by the gateway (ATL-314).
    */
   isPublic?: boolean;
-  /**
-   * When true, the route requires scope-based policy enforcement.
-   * The HTTP server enforces via `enforcePolicy()`. The IPC adapter
-   * includes the resolved policy in the route schema so the gateway's
-   * IPC proxy enforces equivalent scope/principal checks.
-   */
-  requirePolicyEnforcement?: boolean;
   /**
    * Response headers for this route. Can be:
    * - A static map of header name → value

package/src/runtime/routes/ui-request-routes.ts

@@ -4,6 +4,7 @@
 
 import { z } from "zod";
 
+import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import { requestInteractiveUi } from "../interactive-ui.js";
 import { RESERVED_ACTION_IDS } from "../interactive-ui-types.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -46,6 +47,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "ui_request",
     endpoint: "ui/request",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleUiRequest,
     summary: "Present an interactive UI surface",
     description:

package/src/runtime/routes/upgrade-broadcast-routes.ts

@@ -12,6 +12,7 @@ import type {
 } from "../../daemon/message-types/upgrades.js";
 import { buildAssistantEvent } from "../assistant-event.js";
 import { assistantEventHub } from "../assistant-event-hub.js";
+import { GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -124,6 +125,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "upgrade_broadcast",
     endpoint: "admin/upgrade-broadcast",
     method: "POST",
+    policy: {
+      requiredScopes: ["internal.write"],
+      allowedPrincipalTypes: GATEWAY_PRINCIPALS,
+    },
     summary: "Broadcast upgrade lifecycle event",
     description:
       "Publish a service group update lifecycle event (starting, progress, or complete) to all connected SSE clients.",

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

@@ -21,6 +21,7 @@ import {
   type UsageGranularity,
 } from "../../memory/llm-usage-store.js";
 import { validateTimezone } from "../../memory/usage-buckets.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -29,6 +30,52 @@ 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 usageTotalsSchema = z.object({
+  totalInputTokens: z.number(),
+  totalOutputTokens: z.number(),
+  totalCacheCreationTokens: z.number(),
+  totalCacheReadTokens: z.number(),
+  totalEstimatedCostUsd: z.number(),
+  eventCount: z.number(),
+  pricedEventCount: z.number(),
+  unpricedEventCount: z.number(),
+});
+
+const usageDayBucketSchema = z.object({
+  bucketId: z.string(),
+  date: z.string(),
+  displayLabel: z.string().optional(),
+  totalInputTokens: z.number(),
+  totalOutputTokens: z.number(),
+  totalEstimatedCostUsd: z.number(),
+  eventCount: z.number(),
+});
+
+const usageGroupBreakdownSchema = z.object({
+  group: z.string(),
+  groupId: z.string().nullable(),
+  groupKey: z.string().nullable().optional(),
+  totalInputTokens: z.number(),
+  totalOutputTokens: z.number(),
+  totalCacheCreationTokens: z.number(),
+  totalCacheReadTokens: z.number(),
+  totalEstimatedCostUsd: z.number(),
+  eventCount: z.number(),
+});
+
+const usageSeriesGroupValueSchema = z.object({
+  group: z.string(),
+  groupKey: z.string().nullable(),
+  totalInputTokens: z.number(),
+  totalOutputTokens: z.number(),
+  totalEstimatedCostUsd: z.number(),
+  eventCount: z.number(),
+});
+
+const usageSeriesBucketSchema = usageDayBucketSchema.extend({
+  groups: z.record(z.string(), usageSeriesGroupValueSchema),
+});
+
 function resolveTimezone(queryParams: Record<string, string>): string {
   const tz = queryParams.tz ?? "UTC";
   try {
@@ -148,6 +195,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "usage_totals",
     endpoint: "usage/totals",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get usage totals",
     description: "Return aggregate usage totals for a time range.",
     tags: ["usage"],
@@ -163,12 +214,17 @@ export const ROUTES: RouteDefinition[] = [
         description: "End epoch millis (required)",
       },
     ],
+    responseBody: usageTotalsSchema,
     handler: handleUsageTotals,
   },
   {
     operationId: "usage_daily",
     endpoint: "usage/daily",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get daily usage",
     description: "Return per-day usage buckets for a time range.",
     tags: ["usage"],
@@ -195,7 +251,7 @@ export const ROUTES: RouteDefinition[] = [
       },
     ],
     responseBody: z.object({
-      buckets: z.array(z.unknown()).describe("Usage bucket objects"),
+      buckets: z.array(usageDayBucketSchema).describe("Usage bucket objects"),
     }),
     handler: handleUsageDaily,
   },
@@ -203,6 +259,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "usage_breakdown",
     endpoint: "usage/breakdown",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get usage breakdown",
     description:
       "Return grouped usage breakdown. Prefer call_site for user-facing task breakdowns; actor is a legacy/internal dimension.",
@@ -224,7 +284,9 @@ export const ROUTES: RouteDefinition[] = [
       },
     ],
     responseBody: z.object({
-      breakdown: z.array(z.unknown()).describe("Grouped usage entries"),
+      breakdown: z
+        .array(usageGroupBreakdownSchema)
+        .describe("Grouped usage entries"),
     }),
     handler: handleUsageBreakdown,
   },
@@ -232,6 +294,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "usage_series",
     endpoint: "usage/series",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get grouped usage series",
     description:
       "Return usage buckets with per-group values for stacked charts. Prefer call_site for user-facing task stacks.",
@@ -263,7 +329,9 @@ export const ROUTES: RouteDefinition[] = [
       },
     ],
     responseBody: z.object({
-      buckets: z.array(z.unknown()).describe("Grouped usage bucket objects"),
+      buckets: z
+        .array(usageSeriesBucketSchema)
+        .describe("Grouped usage bucket objects"),
     }),
     handler: handleUsageSeries,
   },

package/src/runtime/routes/user-routes-cli.ts

@@ -14,6 +14,7 @@ import { z } from "zod";
 import { getConfig } from "../../config/loader.js";
 import { getPublicBaseUrl } from "../../inbound/public-ingress-urls.js";
 import { getWorkspaceRoutesDir } from "../../util/platform.js";
+import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import { NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -222,6 +223,10 @@ export const ROUTES: RouteDefinition[] = [
   {
     operationId: "user_routes_list",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     endpoint: "user-routes/list",
     handler: handleUserRoutesList,
     summary: "List user-defined route handlers",
@@ -232,6 +237,10 @@ export const ROUTES: RouteDefinition[] = [
   {
     operationId: "user_routes_inspect",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     endpoint: "user-routes/inspect",
     handler: handleUserRoutesInspect,
     summary: "Inspect a user-defined route handler",

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

@@ -14,6 +14,7 @@
 
 import { assistantEventHub } from "../assistant-event-hub.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 import { RouteResponse } from "./types.js";
 import { UserRouteDispatcher } from "./user-route-dispatcher.js";
@@ -108,10 +109,13 @@ export const ROUTES: RouteDefinition[] = METHODS.map((method) => ({
   operationId: `user_route_${method.toLowerCase()}`,
   endpoint: "x/:path*",
   method,
-  policyKey: "x",
   summary: `User-defined ${method} route`,
   description: `Dispatches ${method} requests to user-defined handler files in the workspace routes directory.`,
   tags: ["user-routes"],
+  policy: {
+    requiredScopes: ["settings.read"],
+    allowedPrincipalTypes: ACTOR_PRINCIPALS,
+  },
   handler: async (args: RouteHandlerArgs) => {
     const request = synthesizeRequest(method, args);
     const response = await dispatcher.dispatch(

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

@@ -8,6 +8,7 @@ import { z } from "zod";
 
 import { getConversation } from "../../memory/conversation-crud.js";
 import { wakeAgentForOpportunity } from "../agent-wake.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { NotFoundError } from "./errors.js";
 import type { RouteDefinition } from "./types.js";
 
@@ -22,6 +23,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "wake_conversation",
     endpoint: "conversations/wake",
     method: "POST",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Wake a conversation",
     description:
       "Invoke the agent loop for a conversation with an opportunity hint.",

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

@@ -16,6 +16,7 @@ import {
   listWatchers,
   updateWatcher,
 } from "../../watcher/watcher-store.js";
+import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -192,6 +193,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "watcher_create",
     endpoint: "watchers/create",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleWatcherCreate,
     summary: "Create a watcher",
     description: "Create a new watcher with a provider and action prompt.",
@@ -203,6 +208,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "watcher_list",
     endpoint: "watchers/list",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleWatcherList,
     summary: "List watchers",
     description:
@@ -215,6 +224,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "watcher_update",
     endpoint: "watchers/update",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleWatcherUpdate,
     summary: "Update a watcher",
     description: "Update an existing watcher's configuration.",
@@ -226,6 +239,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "watcher_delete",
     endpoint: "watchers/delete",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleWatcherDelete,
     summary: "Delete a watcher",
     description: "Delete a watcher by ID.",
@@ -237,6 +254,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "watcher_digest",
     endpoint: "watchers/digest",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleWatcherDigest,
     summary: "Get watcher event digest",
     description:

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

@@ -17,6 +17,7 @@ import {
   resolvePlatformCallbackRegistrationContext,
 } from "../../inbound/platform-callback-registration.js";
 import { getPublicBaseUrl } from "../../inbound/public-ingress-urls.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import {
   BadRequestError,
   InternalError,
@@ -146,6 +147,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "webhooks_register",
     endpoint: "webhooks/register",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Register a webhook callback URL",
     description:
       "Resolves a stable callback URL for a webhook type. On platform-managed assistants, registers the route with the platform gateway. On self-hosted assistants, uses the configured ingress.publicBaseUrl.",
@@ -156,6 +161,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "webhooks_list",
     endpoint: "webhooks",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "List registered webhook callback routes",
     description:
       "Lists all webhook callback routes registered with the platform for this assistant.",

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

@@ -5,6 +5,7 @@
 import { z } from "zod";
 
 import { destroyActiveConversation } from "../../daemon/conversation-store.js";
+import { stripConversationIds } from "../../home/feed-writer.js";
 import {
   countConversationsByScheduleJobId,
   getConversation,
@@ -12,6 +13,7 @@ import {
 } from "../../memory/conversation-crud.js";
 import { enqueueMemoryJob } from "../../memory/jobs-store.js";
 import { deleteSchedule } from "../../schedule/schedule-store.js";
+import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import { NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -54,6 +56,8 @@ async function handleWipeConversation({ body = {} }: RouteHandlerArgs) {
     });
   }
 
+  void stripConversationIds(conversationId);
+
   return {
     wiped: true,
     unsupersededItems: 0,
@@ -78,6 +82,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "wipe_conversation",
     endpoint: "conversations/wipe",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleWipeConversation,
     summary: "Wipe a conversation",
     description:

package/src/runtime/routes/work-items-routes.ts

@@ -36,6 +36,7 @@ import {
 } from "../../work-items/work-item-store.js";
 import { buildAssistantEvent } from "../assistant-event.js";
 import { assistantEventHub } from "../assistant-event-hub.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import {
   BadRequestError,
   ConflictError,
@@ -414,7 +415,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "listWorkItems",
     endpoint: "work-items",
     method: "GET",
-    policyKey: "work-items",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "List work items",
     description: "Return work items, optionally filtered by status.",
     tags: ["work-items"],
@@ -452,7 +456,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "getWorkItem",
     endpoint: "work-items/:id",
     method: "GET",
-    policyKey: "work-items",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get a work item",
     description: "Return a single work item by ID.",
     tags: ["work-items"],
@@ -469,7 +476,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "updateWorkItem",
     endpoint: "work-items/:id",
     method: "PATCH",
-    policyKey: "work-items",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Update a work item",
     description:
       "Partially update a work item's title, notes, status, or priority.",
@@ -523,7 +533,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "completeWorkItem",
     endpoint: "work-items/:id/complete",
     method: "POST",
-    policyKey: "work-items/complete",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Complete a work item",
     description: "Transition a work item from awaiting_review to done.",
     tags: ["work-items"],
@@ -552,7 +565,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "deleteWorkItem",
     endpoint: "work-items/:id",
     method: "DELETE",
-    policyKey: "work-items",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Delete a work item",
     description: "Permanently remove a work item.",
     tags: ["work-items"],
@@ -572,7 +588,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "approveWorkItemPermissions",
     endpoint: "work-items/:id/approve-permissions",
     method: "POST",
-    policyKey: "work-items/approve-permissions",
+    policy: {
+      requiredScopes: ["approval.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Approve tool permissions",
     description: "Pre-approve a set of tools for a work item before it runs.",
     tags: ["work-items"],
@@ -601,7 +620,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "preflightWorkItem",
     endpoint: "work-items/:id/preflight",
     method: "POST",
-    policyKey: "work-items/preflight",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Preflight check",
     description: "Check tool permissions needed before running a work item.",
     tags: ["work-items"],
@@ -628,7 +650,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "getWorkItemOutput",
     endpoint: "work-items/:id/output",
     method: "GET",
-    policyKey: "work-items/output",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get work item output",
     description: "Return the final output of a completed work item run.",
     tags: ["work-items"],
@@ -657,7 +682,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "cancelWorkItem",
     endpoint: "work-items/:id/cancel",
     method: "POST",
-    policyKey: "work-items/cancel",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Cancel a running work item",
     description: "Abort a running work item and set its status to cancelled.",
     tags: ["work-items"],
@@ -707,7 +735,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "runWorkItem",
     endpoint: "work-items/:id/run",
     method: "POST",
-    policyKey: "work-items/run",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Run a work item",
     description:
       "Execute the task associated with a work item. Returns immediately; execution happens in the background.",
@@ -797,17 +828,14 @@ export const ROUTES: RouteDefinition[] = [
                 taskConversation.taskRunId = taskRunId;
                 taskConversation.headlessLock = true;
               }
-              await taskConversation.processMessage(
-                message,
-                [],
-                (event) => {
+              await taskConversation.processMessage({
+                content: message,
+                attachments: [],
+                onEvent: (event) => {
                   publishEvent(event);
                 },
-                undefined,
-                undefined,
-                undefined,
-                { isInteractive: false },
-              );
+                isInteractive: false,
+              });
             },
           );
 

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

@@ -7,6 +7,7 @@ import { z } from "zod";
 
 import { getWorkspaceDir } from "../../util/platform.js";
 import { getWorkspaceGitService } from "../../workspace/git-service.js";
+import { GATEWAY_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -28,6 +29,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "workspace_commit",
     endpoint: "admin/workspace-commit",
     method: "POST",
+    policy: {
+      requiredScopes: ["internal.write"],
+      allowedPrincipalTypes: GATEWAY_PRINCIPALS,
+    },
     summary: "Commit workspace changes",
     description:
       "Create a git commit in the workspace directory with all pending changes.",

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

@@ -283,6 +283,48 @@ describe("GET /v1/workspace/tree", () => {
       expect(lastDirIdx).toBeLessThan(firstFileIdx);
     }
   });
+
+  test("includeDirSizes=true returns recursive byte size for directories", () => {
+    const result = handler({ queryParams: { includeDirSizes: "true" } }) as {
+      entries: Array<{ name: string; type: string; size: number | null }>;
+    };
+    const subdirEntry = result.entries.find((e) => e.name === "subdir");
+    expect(subdirEntry).toBeDefined();
+    expect(subdirEntry!.type).toBe("directory");
+    // subdir/nested.txt contains "nested content" (14 bytes) — the only file
+    // under subdir/, so the recursive size equals exactly that file's size.
+    expect(subdirEntry!.size).toBe("nested content".length);
+  });
+
+  test("includeDirSizes=true preserves accurate file sizes", () => {
+    const result = handler({ queryParams: { includeDirSizes: "true" } }) as {
+      entries: Array<{ name: string; type: string; size: number | null }>;
+    };
+    const fileEntry = result.entries.find((e) => e.name === "hello.txt");
+    expect(fileEntry).toBeDefined();
+    expect(fileEntry!.size).toBe("Hello, world!".length);
+  });
+
+  test("includeDirSizes omitted preserves null size for directories", () => {
+    const result = handler({ queryParams: {} }) as {
+      entries: Array<{ type: string; size: number | null }>;
+    };
+    const dirEntry = result.entries.find((e) => e.type === "directory");
+    expect(dirEntry).toBeDefined();
+    expect(dirEntry!.size).toBeNull();
+  });
+
+  test("includeDirSizes=true returns 0 for empty directory", () => {
+    const emptyDir = join(testWorkspaceDir, "empty-for-size");
+    mkdirSync(emptyDir, { recursive: true });
+
+    const result = handler({ queryParams: { includeDirSizes: "true" } }) as {
+      entries: Array<{ name: string; size: number | null }>;
+    };
+    const emptyEntry = result.entries.find((e) => e.name === "empty-for-size");
+    expect(emptyEntry).toBeDefined();
+    expect(emptyEntry!.size).toBe(0);
+  });
 });
 
 // ===========================================================================