@vellumai/assistant 0.8.5 → 0.8.7-dev.202606052118.34cd356

package/src/runtime/routes/surface-action-routes.ts

@@ -11,15 +11,9 @@ import { z } from "zod";
 
 import type { ChannelId } from "../../channels/types.js";
 import { isHttpAuthDisabled } from "../../config/env.js";
-import type { Conversation } from "../../daemon/conversation.js";
-import {
-  findConversation,
-  findConversationBySurfaceId,
-  getOrCreateConversation,
-} from "../../daemon/conversation-store.js";
-import { rawGet } from "../../memory/raw-query.js";
 import { getLogger } from "../../util/logger.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { healGuardianBindingDrift } from "../guardian-vellum-migration.js";
 import { resolveLocalTrustContext } from "../local-actor-identity.js";
 import {
@@ -27,6 +21,7 @@ import {
   withSourceChannel,
 } from "../trust-context-resolver.js";
 import { BadRequestError, InternalError, NotFoundError, RouteError } from "./errors.js";
+import { resolveSurfaceConversation } from "./surface-conversation-resolver.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("surface-action-routes");
@@ -90,37 +85,6 @@ function applyTrustContext(
   }
 }
 
-/**
- * Resolve the conversation owning a surface, rehydrating from the DB when
- * the in-memory lookup misses (daemon restart or LRU eviction). The DB scan
- * is also the source of truth that the surface exists — without it,
- * `getOrCreateConversation` would silently create a phantom conversation
- * for any caller-supplied id.
- */
-async function resolveSurfaceConversation(
-  conversationId: string | null | undefined,
-  surfaceId: string,
-): Promise<Conversation | undefined> {
-  const found = conversationId
-    ? findConversation(conversationId)
-    : findConversationBySurfaceId(surfaceId);
-  if (found) return found;
-
-  // Escape LIKE wildcards so a `surfaceId` like "%" or "_" can't match
-  // unrelated rows.
-  const escaped = surfaceId.replace(/[\\%_]/g, "\\$&");
-  const row = rawGet<{ conversation_id: string }>(
-    `SELECT conversation_id FROM messages
-     WHERE content LIKE ? ESCAPE '\\'
-     ORDER BY created_at DESC
-     LIMIT 1`,
-    `%"surfaceId":"${escaped}"%`,
-  );
-  if (!row) return undefined;
-  if (conversationId && conversationId !== row.conversation_id) return undefined;
-  return await getOrCreateConversation(row.conversation_id);
-}
-
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
@@ -262,6 +226,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "triggerSurfaceAction",
     endpoint: "surface-actions",
     method: "POST",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Trigger a surface action",
     description:
       "Execute an interactive action on a surface (e.g. button click, form submit).",
@@ -294,6 +262,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "undoSurfaceAction",
     endpoint: "surfaces/:id/undo",
     method: "POST",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Undo last surface action",
     description: "Revert the most recent action on a surface.",
     tags: ["surfaces"],

package/src/runtime/routes/surface-content-routes.ts

@@ -2,14 +2,17 @@
  * Route handler for fetching surface content by ID.
  *
  * GET /v1/surfaces/:surfaceId — return the full surface payload from the
- * conversation's in-memory surface state. Used by clients to re-hydrate surfaces
- * whose data was stripped during memory compaction.
+ * conversation's in-memory surface state. Used by clients to re-hydrate
+ * surfaces whose data was stripped during memory compaction, or whose
+ * owning conversation has been evicted from the daemon's in-memory map
+ * (daemon restart, LRU eviction).
  */
 import { z } from "zod";
 
-import { findConversation } from "../../daemon/conversation-store.js";
 import { getLogger } from "../../util/logger.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError, NotFoundError } from "./errors.js";
+import { resolveSurfaceConversation } from "./surface-conversation-resolver.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("surface-content-routes");
@@ -18,7 +21,7 @@ const log = getLogger("surface-content-routes");
 // GET /v1/surfaces/:surfaceId?conversationId=...
 // ---------------------------------------------------------------------------
 
-function handleGetSurfaceContent({
+async function handleGetSurfaceContent({
   pathParams = {},
   queryParams = {},
 }: RouteHandlerArgs) {
@@ -32,7 +35,15 @@ function handleGetSurfaceContent({
     throw new BadRequestError("surfaceId path parameter is required");
   }
 
-  const conversation = findConversation(conversationId);
+  // Resolve via the shared surface→conversation helper: in-memory first,
+  // falling back to a DB scan that rehydrates the conversation when the
+  // owning Conversation has been evicted or the daemon was restarted. The
+  // DB scan uses the surfaceId itself as the existence check so a stale
+  // or made-up conversationId can't materialize a phantom conversation.
+  const conversation = await resolveSurfaceConversation(
+    conversationId,
+    surfaceId,
+  );
   if (!conversation) {
     throw new NotFoundError(
       "No active conversation found for this conversationId",
@@ -84,6 +95,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "surfaces_get_content",
     endpoint: "surfaces/:surfaceId",
     method: "GET",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Get surface content",
     description:
       "Return the full surface payload from the conversation's in-memory surface state.",
@@ -99,7 +114,7 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({
       surfaceId: z.string(),
       surfaceType: z.string(),
-      title: z.string(),
+      title: z.string().nullable(),
       data: z.object({}).passthrough().describe("Surface data payload"),
     }),
     handler: handleGetSurfaceContent,

package/src/runtime/routes/surface-conversation-resolver.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared helper for resolving the conversation that owns a surface.
+ *
+ * Used by both `surface-action-routes` (POST /v1/surface-actions) and
+ * `surface-content-routes` (GET /v1/surfaces/:surfaceId) so the
+ * in-memory-miss → DB-scan → rehydrate flow stays in one place.
+ *
+ * Why this exists: surfaces live on the in-memory `Conversation` object
+ * (`surfaceState` is rebuilt from `ui_surface` blocks in message
+ * history by `restoreSurfaceStateFromHistory()` whenever a Conversation
+ * is constructed). A bare `findConversation` lookup 404s after daemon
+ * restart or LRU eviction even though the surface data is still in the
+ * SQLite `messages` table. The DB scan below uses the surfaceId itself
+ * as the existence check so `getOrCreateConversation` can't be tricked
+ * into materializing a phantom conversation for any caller-supplied id.
+ */
+import type { Conversation } from "../../daemon/conversation.js";
+import {
+  findConversation,
+  findConversationBySurfaceId,
+} from "../../daemon/conversation-registry.js";
+import { getOrCreateConversation } from "../../daemon/conversation-store.js";
+import { rawGet } from "../../memory/raw-query.js";
+
+/**
+ * Resolve the {@link Conversation} that owns the given surface.
+ *
+ * Lookup order:
+ * 1. In-memory map keyed by `conversationId` (or by `surfaceId` when no
+ *    id is supplied).
+ * 2. SQLite `messages` table — find the conversation whose history
+ *    contains a `ui_surface` block with this `surfaceId`. The result is
+ *    validated against the caller's `conversationId` (when supplied) so
+ *    a mismatched pair returns `undefined` rather than silently
+ *    re-routing to a different conversation.
+ * 3. `getOrCreateConversation` rehydrates the row, which triggers
+ *    `restoreSurfaceStateFromHistory()` and repopulates `surfaceState`.
+ *
+ * Returns `undefined` when neither lookup nor DB scan turns up a
+ * matching conversation. Callers are expected to translate that into
+ * the route-appropriate 404.
+ */
+export async function resolveSurfaceConversation(
+  conversationId: string | null | undefined,
+  surfaceId: string,
+): Promise<Conversation | undefined> {
+  const found = conversationId
+    ? findConversation(conversationId)
+    : findConversationBySurfaceId(surfaceId);
+  if (found) return found;
+
+  // Escape LIKE wildcards so a `surfaceId` like "%" or "_" can't match
+  // unrelated rows.
+  const escaped = surfaceId.replace(/[\\%_]/g, "\\$&");
+  const row = rawGet<{ conversation_id: string }>(
+    `SELECT conversation_id FROM messages
+     WHERE content LIKE ? ESCAPE '\\'
+     ORDER BY created_at DESC
+     LIMIT 1`,
+    `%"surfaceId":"${escaped}"%`,
+  );
+  if (!row) return undefined;
+  if (conversationId && conversationId !== row.conversation_id)
+    return undefined;
+  return await getOrCreateConversation(row.conversation_id);
+}

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

@@ -8,6 +8,7 @@ import { z } from "zod";
 import { broadcastMessage } from "../../runtime/assistant-event-hub.js";
 import type { ToolContext } from "../../tools/types.js";
 import { getWorkspaceDir } from "../../util/platform.js";
+import { LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -255,6 +256,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_save",
     endpoint: "tasks/save",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskSave,
     summary: "Save a task template",
     description: "Save the current conversation as a reusable task template.",
@@ -266,6 +271,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_list",
     endpoint: "tasks/list",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskList,
     summary: "List task templates",
     description: "List all saved task templates.",
@@ -276,6 +285,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_run",
     endpoint: "tasks/run",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskRun,
     summary: "Run a task template",
     description: "Execute a saved task template by name or ID.",
@@ -287,6 +300,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_delete",
     endpoint: "tasks/delete",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskDelete,
     summary: "Delete task templates",
     description: "Delete one or more task templates by ID.",
@@ -300,6 +317,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_queue_show",
     endpoint: "tasks/queue/show",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskQueueShow,
     summary: "Show task queue",
     description: "List work items in the task queue, optionally filtered by status.",
@@ -311,6 +332,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_queue_add",
     endpoint: "tasks/queue/add",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskQueueAdd,
     summary: "Add to task queue",
     description: "Add a new work item to the task queue.",
@@ -322,6 +347,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_queue_update",
     endpoint: "tasks/queue/update",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskQueueUpdate,
     summary: "Update a task queue item",
     description: "Update an existing work item in the task queue.",
@@ -333,6 +362,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_queue_remove",
     endpoint: "tasks/queue/remove",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskQueueRemove,
     summary: "Remove from task queue",
     description: "Remove a work item from the task queue.",
@@ -344,6 +377,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "task_queue_run",
     endpoint: "tasks/queue/run",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: LOCAL_PRINCIPALS,
+    },
     handler: handleTaskQueueRun,
     summary: "Run next task queue item",
     description: "Pick up and execute the next work item from the queue.",

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

@@ -9,6 +9,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 { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -47,6 +48,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "telemetry_lifecycle",
     endpoint: "telemetry/lifecycle",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Record lifecycle event",
     description: "Record a telemetry lifecycle event (app_open, hatch).",
     tags: ["telemetry"],
@@ -72,6 +77,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "telemetry_flush",
     endpoint: "telemetry/flush",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Flush pending telemetry events",
     description:
       "Force-flush all pending usage, turn, and lifecycle telemetry events to the platform.",

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/trace-event-routes.ts

@@ -7,9 +7,46 @@
 import { z } from "zod";
 
 import { getTraceEvents } from "../../memory/trace-event-store.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { BadRequestError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
+const traceEventKindSchema = z.enum([
+  "request_received",
+  "request_queued",
+  "request_dequeued",
+  "llm_call_started",
+  "llm_call_finished",
+  "assistant_message",
+  "tool_started",
+  "tool_permission_requested",
+  "tool_permission_decided",
+  "tool_finished",
+  "tool_failed",
+  "generation_handoff",
+  "message_complete",
+  "generation_cancelled",
+  "request_error",
+  "tool_profiling_summary",
+]);
+
+const traceEventRowSchema = z.object({
+  eventId: z.string(),
+  conversationId: z.string(),
+  requestId: z.string().optional(),
+  timestampMs: z.number(),
+  sequence: z.number(),
+  kind: traceEventKindSchema,
+  status: z.enum(["info", "success", "warning", "error"]).optional(),
+  summary: z.string(),
+  attributes: z
+    .record(
+      z.string(),
+      z.union([z.string(), z.number(), z.boolean(), z.null()]),
+    )
+    .optional(),
+});
+
 function handleListTraceEvents({ queryParams }: RouteHandlerArgs) {
   const conversationId = queryParams?.conversationId;
   if (!conversationId) {
@@ -44,6 +81,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "trace_events_list",
     endpoint: "trace-events",
     method: "GET",
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "List trace events",
     description: "Return persisted trace events for a conversation.",
     tags: ["trace"],
@@ -64,7 +105,7 @@ export const ROUTES: RouteDefinition[] = [
       },
     ],
     responseBody: z.object({
-      events: z.array(z.unknown()).describe("Trace event objects"),
+      events: z.array(traceEventRowSchema).describe("Trace event objects"),
     }),
     handler: handleListTraceEvents,
   },