@vellumai/assistant 0.7.2 → 0.8.0

package/src/runtime/auth/same-actor.ts

@@ -0,0 +1,216 @@
+/**
+ * Same-actor (same-user) binding check used by host proxies and result
+ * routes.
+ *
+ * Verifies that the submitting (source) actor's principal id matches the
+ * actor principal id captured for the target client at SSE subscription
+ * time. This is the authoritative gate that prevents cross-user
+ * execution and cross-user result submission across all three host-proxy
+ * capabilities (host_bash, host_file, host_cu).
+ *
+ * Two entry points map onto the two control-flow styles in the codebase:
+ *   - {@link enforceSameActorOrErrorResult} for proxies — returns a
+ *     tool-execution error result on rejection, `null` on success.
+ *   - {@link enforceSameActorOrThrow} for HTTP/IPC route handlers —
+ *     throws {@link ForbiddenError} on rejection so the route adapter
+ *     maps it to HTTP 403.
+ *
+ * Both paths log a single structured warn line on rejection with the
+ * shape `{ sourceActorPrincipalId, targetClientId, targetActorPrincipalId,
+ * op, reason }` so that bash, file, and CU rejections render identically
+ * in the audit log.
+ */
+import type { HostProxyCapability } from "../../channels/types.js";
+import { getLogger } from "../../util/logger.js";
+import type { AssistantEventHub } from "../assistant-event-hub.js";
+import { ForbiddenError } from "../routes/errors.js";
+
+const log = getLogger("same-actor");
+
+/**
+ * Canonical user-facing rejection message. Used by both the proxy and
+ * route paths so operators and auditors see identical wording regardless
+ * of whether the failure surfaced as a tool-execution result or an HTTP
+ * 403.
+ */
+const REJECTION_MESSAGE =
+  "Submitting actor does not match the target client's actor for this request. The targeted client's authenticated user must submit the result.";
+
+/** OpenAPI 403 description for `*-result` endpoints, kept identical. */
+export const SAME_ACTOR_FORBIDDEN_DESCRIPTION =
+  "Submitting client does not match the targeted client, or the submitting actor's principal does not match the target client's actor.";
+
+/** Per-capability scope for the structured warn log entry. */
+export type SameActorOp =
+  | "host_bash"
+  | "host_file"
+  | "host_cu"
+  | "host_transfer";
+
+/**
+ * Args for the live-lookup variant: caller supplies the hub + target client
+ * id, and the helper looks up the target's actor principal in real time.
+ * Used at proxy request time (registration), where the SSE subscription is
+ * present by definition.
+ */
+export interface SameActorLiveArgs {
+  hub: Pick<AssistantEventHub, "getActorPrincipalIdForClient">;
+  sourceActorPrincipalId: string | undefined;
+  targetClientId: string;
+  op: SameActorOp;
+}
+
+/**
+ * Args for the persisted-value variant: caller supplies a target actor
+ * principal id captured at registration time. Used at result-submission
+ * time, where the SSE subscription may have briefly disconnected and the
+ * live hub lookup would falsely 403 a legitimate result.
+ */
+export interface SameActorPersistedArgs {
+  sourceActorPrincipalId: string | undefined;
+  targetActorPrincipalId: string | undefined;
+  targetClientId: string;
+  op: SameActorOp;
+}
+
+export type SameActorArgs = SameActorLiveArgs;
+
+type RejectionReason = "missing_source" | "missing_target" | "mismatch";
+
+function isLive(
+  args: SameActorLiveArgs | SameActorPersistedArgs,
+): args is SameActorLiveArgs {
+  return (args as SameActorLiveArgs).hub != null;
+}
+
+/**
+ * Internal: returns the rejection reason or `undefined` when the source
+ * matches the target. Always logs on rejection so all callers share the
+ * same audit shape.
+ */
+function detectRejection(
+  args: SameActorLiveArgs | SameActorPersistedArgs,
+): RejectionReason | undefined {
+  const { sourceActorPrincipalId, targetClientId, op } = args;
+  const targetActorPrincipalId = isLive(args)
+    ? args.hub.getActorPrincipalIdForClient(targetClientId)
+    : args.targetActorPrincipalId;
+
+  let reason: RejectionReason | undefined;
+  if (sourceActorPrincipalId == null) {
+    reason = "missing_source";
+  } else if (targetActorPrincipalId == null) {
+    reason = "missing_target";
+  } else if (sourceActorPrincipalId !== targetActorPrincipalId) {
+    reason = "mismatch";
+  }
+  if (reason == null) return undefined;
+
+  log.warn(
+    {
+      sourceActorPrincipalId,
+      targetClientId,
+      targetActorPrincipalId,
+      op,
+      reason,
+    },
+    "Rejecting cross-user host proxy request",
+  );
+  return reason;
+}
+
+/**
+ * Route-flavored variant: throws {@link ForbiddenError} on rejection so
+ * the existing route adapter maps it to HTTP 403. Returns void on
+ * success.
+ *
+ * Accepts EITHER {@link SameActorLiveArgs} (live hub lookup, used at
+ * proxy registration time) OR {@link SameActorPersistedArgs} (compare
+ * against a value captured earlier, used at result-submission time so a
+ * brief SSE reconnect doesn't 403 a legitimate result).
+ */
+export function enforceSameActorOrThrow(
+  args: SameActorLiveArgs | SameActorPersistedArgs,
+): void {
+  if (detectRejection(args) != null) {
+    throw new ForbiddenError(REJECTION_MESSAGE);
+  }
+}
+
+/**
+ * Proxy-flavored variant: returns a tool-execution-shaped error result
+ * on rejection (so the proxy can pass it directly back to the agent),
+ * or `null` on success. Always uses the live hub lookup — proxy
+ * registration runs while the target SSE subscription is active.
+ */
+export function enforceSameActorOrErrorResult(
+  args: SameActorLiveArgs,
+): { content: string; isError: true } | null {
+  if (detectRejection(args) == null) return null;
+  return { content: REJECTION_MESSAGE, isError: true };
+}
+
+/**
+ * Result of attempting to auto-resolve a single same-user target client.
+ *
+ * - `match`: exactly one same-user client supports the capability. Use the
+ *   returned clientId.
+ * - `none`: no same-user client supports the capability. Caller's choice
+ *   how to handle (typically: fall through to no-target, which broadcasts
+ *   to nobody when no clients are connected).
+ * - `ambiguous`: more than one same-user client supports the capability.
+ *   Caller MUST refuse to silently broadcast across them; instead surface
+ *   an error asking the caller to specify `target_client_id`.
+ */
+export type AutoResolveResult =
+  | { kind: "match"; clientId: string }
+  | { kind: "none" }
+  | { kind: "ambiguous" };
+
+/**
+ * Filter capable clients by `actorPrincipalId === sourcePrincipalId` and
+ * report whether exactly one matched, zero matched, or more than one
+ * matched.
+ *
+ * Used by host proxies to auto-resolve a target client when the caller
+ * did not specify one. Skipping when the caller has no principal keeps
+ * the same-user binding closed: an unauthenticated caller cannot
+ * piggyback on a connected user's session.
+ *
+ * Why three outcomes (vs. just `string | undefined`)? Earlier revisions
+ * collapsed `none` and `ambiguous` into `undefined`, which caused the
+ * proxy to fall through to an untargeted broadcast — fanning a single
+ * targeted-style request out across every same-user machine. Surfacing
+ * `ambiguous` separately lets the proxy reject with a clear "specify
+ * target_client_id" error instead.
+ */
+export function pickSameUserAutoResolve(args: {
+  hub: Pick<AssistantEventHub, "listClientsByCapability">;
+  capability: HostProxyCapability;
+  sourceActorPrincipalId: string | undefined;
+}): AutoResolveResult {
+  const { hub, capability, sourceActorPrincipalId } = args;
+  if (sourceActorPrincipalId == null) return { kind: "none" };
+  const sameUser = hub
+    .listClientsByCapability(capability)
+    .filter((c) => c.actorPrincipalId === sourceActorPrincipalId);
+  if (sameUser.length === 0) return { kind: "none" };
+  if (sameUser.length === 1) {
+    return { kind: "match", clientId: sameUser[0].clientId };
+  }
+  return { kind: "ambiguous" };
+}
+
+/**
+ * Standard error result for proxies when {@link pickSameUserAutoResolve}
+ * returns `ambiguous`. Asks the caller to specify `target_client_id`.
+ */
+export function ambiguousSameUserError(capability: HostProxyCapability): {
+  content: string;
+  isError: true;
+} {
+  return {
+    content: `Multiple ${capability} clients are connected for this user. Specify target_client_id to disambiguate. Run \`assistant clients list --capability ${capability}\` to see client IDs.`,
+    isError: true,
+  };
+}

package/src/runtime/channel-approvals.ts

@@ -160,8 +160,9 @@ export function handleChannelDecision(
     : pending[0];
   if (!info) return { applied: false };
 
-  // Resolve the interaction to get the conversation and remove from tracker
-  const resolved = pendingInteractions.resolve(info.requestId);
+  // Peek (not consume) — resolveConfirmation() owns deregistration and
+  // must fire the promptResolve callback stored in the interaction.
+  const resolved = pendingInteractions.get(info.requestId);
   if (!resolved) return { applied: false };
 
   // Map channel-level action to the permission system's UserDecision type.

package/src/runtime/channel-retry-sweep.ts

@@ -7,9 +7,11 @@ import {
   parseChannelId,
   parseInterfaceId,
 } from "../channels/types.js";
+import { getDiskPressureStatus } from "../daemon/disk-pressure-guard.js";
+import { classifyDiskPressureTurnPolicy } from "../daemon/disk-pressure-policy.js";
 import type { TrustContext } from "../daemon/trust-context.js";
 import { updateDeliveredSegmentCount } from "../memory/delivery-channels.js";
-import { linkMessage } from "../memory/delivery-crud.js";
+import { clearPayload, linkMessage } from "../memory/delivery-crud.js";
 import {
   getRetryableEvents,
   markProcessed,
@@ -18,10 +20,13 @@ import {
 } from "../memory/delivery-status.js";
 import { getLogger } from "../util/logger.js";
 import { deliverReplyViaCallback } from "./channel-reply-delivery.js";
+import { deliverChannelReply } from "./gateway-client.js";
 import type { MessageProcessor } from "./http-types.js";
 import { resolveRoutingStateFromRuntime } from "./trust-context-resolver.js";
 
 const log = getLogger("runtime-http");
+const DISK_PRESSURE_REMOTE_BLOCK_REPLY =
+  "Storage is critically low, so remote messages are ignored until the guardian frees enough space. Please try again later.";
 
 function parseTrustRuntimeContext(value: unknown): TrustContext | undefined {
   if (!value || typeof value !== "object") return undefined;
@@ -163,6 +168,65 @@ export async function sweepFailedEvents(
       trustClass: "unknown",
     };
 
+    const diskPressureDecision = classifyDiskPressureTurnPolicy(
+      getDiskPressureStatus(),
+      {
+        sourceChannel,
+        sourceInterface,
+        trustContext: {
+          sourceChannel: trustContext.sourceChannel,
+          trustClass: trustContext.trustClass,
+        },
+      },
+    );
+    if (diskPressureDecision.action === "block") {
+      clearPayload(event.id);
+      markProcessed(event.id);
+      log.info(
+        {
+          eventId: event.id,
+          conversationId: event.conversationId,
+          reason: diskPressureDecision.reason,
+          trustClass: trustContext.trustClass,
+        },
+        "Skipped channel retry during disk pressure cleanup mode",
+      );
+
+      const replyCallbackUrl =
+        typeof payload.replyCallbackUrl === "string"
+          ? payload.replyCallbackUrl
+          : undefined;
+      const externalChatId =
+        typeof payload.externalChatId === "string"
+          ? payload.externalChatId
+          : undefined;
+      if (replyCallbackUrl && externalChatId) {
+        const requesterExternalUserId =
+          trustContext.requesterExternalUserId ??
+          (typeof payload.senderExternalUserId === "string"
+            ? payload.senderExternalUserId
+            : undefined);
+        const replyPayload: Parameters<typeof deliverChannelReply>[1] = {
+          chatId: externalChatId,
+          text: DISK_PRESSURE_REMOTE_BLOCK_REPLY,
+          assistantId,
+        };
+        if (sourceChannel === "slack" && requesterExternalUserId) {
+          replyPayload.ephemeral = true;
+          replyPayload.user = requesterExternalUserId;
+        }
+        try {
+          await deliverChannelReply(replyCallbackUrl, replyPayload);
+        } catch (err) {
+          log.warn(
+            { err, eventId: event.id, conversationId: event.conversationId },
+            "Failed to deliver disk pressure retry block reply",
+          );
+        }
+      }
+      continue;
+    }
+
     const metadataHintsRaw = sourceMetadata?.hints;
     const metadataHints = Array.isArray(metadataHintsRaw)
       ? metadataHintsRaw.filter(

package/src/runtime/local-actor-identity.ts

@@ -12,6 +12,7 @@
  */
 
 import type { ChannelId } from "../channels/types.js";
+import { isHttpAuthDisabled } from "../config/env.js";
 import { findGuardianForChannel } from "../contacts/contact-store.js";
 import type { TrustContext } from "../daemon/trust-context.js";
 import { getLogger } from "../util/logger.js";
@@ -43,6 +44,52 @@ export function buildLocalAuthContext(conversationId: string): AuthContext {
   };
 }
 
+/**
+ * Look up the local vellum guardian's principalId from the contacts table.
+ *
+ * Returns `undefined` when no vellum guardian binding exists (e.g. fresh
+ * install before bootstrap). Callers should treat that case as
+ * "not yet available" and either fall back or proceed without a principalId.
+ */
+export function findLocalGuardianPrincipalId(): string | undefined {
+  return findGuardianForChannel("vellum")?.contact.principalId ?? undefined;
+}
+
+/**
+ * Translate the synthetic dev-bypass actor principal to the real local
+ * guardian's principalId when running in `DISABLE_HTTP_AUTH=true` mode.
+ *
+ * The dev-bypass `AuthContext` (`runtime/auth/middleware.ts`) injects
+ * `"dev-bypass"` as the actor principal id for every request, but tool-side
+ * trust resolution (`resolveLocalTrustContext`) and SSE registration both
+ * carry the real local guardian principalId. Without this translation, every
+ * targeted host_bash/host_file/host_cu/host_transfer result POST mismatches
+ * the same-user check and is rejected with 403, and conversation/surface/
+ * guardian-action routes resolve trust against the wrong principal.
+ *
+ * Returns the input unchanged when:
+ *   - HTTP auth is enabled (production / non-dev-bypass deployments), OR
+ *   - the input is not literally `"dev-bypass"` (e.g. service tokens).
+ *
+ * Returns the local guardian principalId when both gates are true. Returns
+ * `undefined` when dev-bypass is set but no guardian binding has been created
+ * yet (e.g. fresh install before bootstrap); callers must treat this the
+ * same as a missing principal.
+ */
+export function resolveActorPrincipalIdForLocalGuardian(
+  rawHeader: string | undefined,
+): string | undefined {
+  if (rawHeader !== "dev-bypass" || !isHttpAuthDisabled()) return rawHeader;
+
+  const guardianPrincipalId = findLocalGuardianPrincipalId();
+  if (guardianPrincipalId) return guardianPrincipalId;
+
+  log.warn(
+    "dev-bypass actor principal received but no vellum guardian binding found; returning undefined",
+  );
+  return undefined;
+}
+
 /**
  * Resolve the guardian runtime context for a local connection.
  *
@@ -60,10 +107,8 @@ export function resolveLocalTrustContext(
 ): TrustContext {
   const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
 
-  // Try contacts-first for the vellum guardian channel
-  const guardianResult = findGuardianForChannel("vellum");
-  if (guardianResult && guardianResult.contact.principalId) {
-    const guardianPrincipalId = guardianResult.contact.principalId;
+  const guardianPrincipalId = findLocalGuardianPrincipalId();
+  if (guardianPrincipalId) {
     const trustCtx = resolveTrustContext({
       assistantId,
       sourceChannel: "vellum",
@@ -97,13 +142,9 @@ export function resolveLocalTrustContext(
 export function resolveLocalAuthContext(conversationId: string): AuthContext {
   const authContext = buildLocalAuthContext(conversationId);
 
-  // Enrich with the guardian principal ID from contacts-first path
-  const guardianResult = findGuardianForChannel("vellum");
-  if (guardianResult && guardianResult.contact.principalId) {
-    return {
-      ...authContext,
-      actorPrincipalId: guardianResult.contact.principalId,
-    };
+  const guardianPrincipalId = findLocalGuardianPrincipalId();
+  if (guardianPrincipalId) {
+    return { ...authContext, actorPrincipalId: guardianPrincipalId };
   }
 
   log.warn(

package/src/runtime/pending-interactions.ts

@@ -3,22 +3,22 @@
  * confirmation, secret, host_bash, host_file, host_cu, host_browser, and
  * host_transfer interactions.
  *
- * For confirmation_request and secret_request, the onEvent callback in
- * assistant-event-hub registers the interaction here.
+ * All request types self-register with their full RPC lifecycle state
+ * (resolve/reject callbacks, timer, abort detach):
  *
- * For host proxy interactions (host_bash, host_file, host_cu, host_browser,
- * host_transfer), the proxy itself registers with full RPC lifecycle state
- * (resolve/reject callbacks, timer, abort detach). This eliminates the
- * per-proxy `private pending` maps — all pending state lives here.
+ * - Host proxies (host_bash, host_file, host_cu, host_browser,
+ *   host_app_control, host_transfer): register in request(), using
+ *   rpcResolve/rpcReject/timer/detachAbort/metadata.
+ *
+ * - Prompters (PermissionPrompter, SecretPrompter): register in prompt(),
+ *   using promptResolve/promptReject/timer/toolUseId.
  *
  * Standalone HTTP endpoints (/v1/confirm, /v1/secret, /v1/trust-rules,
- * /v1/host-bash-result, /v1/host-file-result, /v1/host-cu-result,
- * /v1/host-browser-result) look up the conversation from this tracker to
+ * /v1/host-bash-result, etc.) look up the conversation from this tracker to
  * resolve the interaction.
  */
 
 import type { UserDecision } from "../permissions/types.js";
-import type { ToolExecutionResult } from "../tools/types.js";
 
 export interface ConfirmationDetails {
   toolName: string;
@@ -59,19 +59,29 @@ export interface PendingInteraction {
   directResolve?: (decision: UserDecision) => void;
   /** When set, the host_bash request should be routed to this specific client. */
   targetClientId?: string;
+  /**
+   * Snapshot of `targetClientId`'s `actorPrincipalId` taken at registration
+   * time. Persisted so the result-route same-actor check compares against
+   * a stable value rather than the live hub — the target client's SSE
+   * subscription may have briefly disconnected between dispatch and result
+   * submission, which would otherwise 403 a legitimate result.
+   */
+  targetActorPrincipalId?: string;
 
-  // -- RPC lifecycle (populated by host proxies) --
+  // -- RPC lifecycle (all interaction types) --
 
-  /** Resolve the caller's Promise with a tool execution result. */
-  rpcResolve?: (result: ToolExecutionResult) => void;
+  /** Resolve the caller's Promise. Typed as unknown; callers cast at use sites. */
+  rpcResolve?: (value: unknown) => void;
   /** Reject the caller's Promise with an error. */
   rpcReject?: (err: Error) => void;
-  /** Proxy-side timeout timer. Cleared on resolve/abort/dispose. */
+  /** Timeout timer. Cleared automatically on resolve(). */
   timer?: ReturnType<typeof setTimeout>;
   /** Detach the abort listener from the caller's signal. No-op when no signal was passed. */
   detachAbort?: () => void;
   /** Proxy-specific metadata (e.g. timeoutSec for bash, operation/path for file). */
   metadata?: Record<string, unknown>;
+  /** toolUseId associated with a confirmation_request (PermissionPrompter). */
+  toolUseId?: string;
 }
 
 const pending = new Map<string, PendingInteraction>();
@@ -136,7 +146,8 @@ export function getByConversation(
  * proxy timer would fire with a spurious timeout error.
  */
 export function removeByConversation(conversationId: string): void {
-  for (const [requestId, interaction] of pending) {
+  // Snapshot keys to avoid mutation-during-iteration.
+  for (const [requestId, interaction] of [...pending]) {
     if (
       interaction.conversationId === conversationId &&
       interaction.kind !== "host_bash" &&
@@ -147,7 +158,8 @@ export function removeByConversation(conversationId: string): void {
       interaction.kind !== "host_transfer" &&
       interaction.kind !== "acp_confirmation"
     ) {
-      pending.delete(requestId);
+      // resolve() clears the stored timer and detaches abort listeners.
+      resolve(requestId);
     }
   }
 }

package/src/runtime/routes/__tests__/client-routes.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Tests for the GET /v1/clients (list_clients) route.
+ *
+ * Validates the same-user filter applied to client listings:
+ * - Caller sees only clients owned by their `actorPrincipalId`.
+ * - Clients with no stored `actorPrincipalId` are filtered out (fail-closed).
+ * - Dev-bypass mode (`isHttpAuthDisabled()`) returns all clients.
+ */
+
+import { afterAll, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ── Module mocks (must be set up before importing the route) ──────────────
+
+let fakeHttpAuthDisabled = false;
+
+mock.module("../../../config/env.js", () => ({
+  isHttpAuthDisabled: () => fakeHttpAuthDisabled,
+  hasUngatedHttpAuthDisabled: () => false,
+}));
+
+mock.module("../../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+// ── Real imports (after mocks) ────────────────────────────────────────────
+
+import { assistantEventHub } from "../../assistant-event-hub.js";
+import { ROUTES } from "../client-routes.js";
+import type { RouteDefinition } from "../types.js";
+
+afterAll(() => {
+  mock.restore();
+});
+
+// ── Test helpers ──────────────────────────────────────────────────────────
+
+function findHandler(operationId: string): RouteDefinition["handler"] {
+  const route = ROUTES.find((r) => r.operationId === operationId);
+  if (!route) throw new Error(`Route ${operationId} not found`);
+  return route.handler;
+}
+
+type ListClientsResponse = {
+  clients: Array<{
+    clientId: string;
+    interfaceId: string;
+    capabilities: string[];
+    machineName?: string;
+    connectedAt: string;
+    lastActiveAt: string;
+  }>;
+};
+
+function registerClient(args: {
+  clientId: string;
+  actorPrincipalId?: string;
+}): void {
+  assistantEventHub.subscribe({
+    type: "client",
+    clientId: args.clientId,
+    interfaceId: "macos",
+    capabilities: ["host_bash", "host_file", "host_cu"],
+    actorPrincipalId: args.actorPrincipalId,
+    callback: () => {},
+  });
+}
+
+function clearHub(): void {
+  const ids = assistantEventHub.listClients().map((c) => c.clientId);
+  for (const id of ids) {
+    assistantEventHub.disposeClient(id);
+  }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────
+
+describe("list_clients route — same-user filter", () => {
+  beforeEach(() => {
+    fakeHttpAuthDisabled = false;
+    clearHub();
+  });
+
+  test("returns only clients owned by the calling actor", () => {
+    registerClient({ clientId: "client-A1", actorPrincipalId: "user-A" });
+    registerClient({ clientId: "client-A2", actorPrincipalId: "user-A" });
+    registerClient({ clientId: "client-B1", actorPrincipalId: "user-B" });
+
+    const handler = findHandler("list_clients");
+    const result = handler({
+      headers: { "x-vellum-actor-principal-id": "user-A" },
+    }) as ListClientsResponse;
+
+    const ids = result.clients.map((c) => c.clientId).sort();
+    expect(ids).toEqual(["client-A1", "client-A2"]);
+  });
+
+  test("filters out cross-user clients when listing as a different user", () => {
+    registerClient({ clientId: "client-A1", actorPrincipalId: "user-A" });
+    registerClient({ clientId: "client-B1", actorPrincipalId: "user-B" });
+
+    const handler = findHandler("list_clients");
+    const result = handler({
+      headers: { "x-vellum-actor-principal-id": "user-B" },
+    }) as ListClientsResponse;
+
+    const ids = result.clients.map((c) => c.clientId);
+    expect(ids).toEqual(["client-B1"]);
+  });
+
+  test("filters out clients with no stored actorPrincipalId (fail-closed)", () => {
+    registerClient({
+      clientId: "client-noprincipal",
+      actorPrincipalId: undefined,
+    });
+    registerClient({ clientId: "client-A1", actorPrincipalId: "user-A" });
+
+    const handler = findHandler("list_clients");
+    const result = handler({
+      headers: { "x-vellum-actor-principal-id": "user-A" },
+    }) as ListClientsResponse;
+
+    const ids = result.clients.map((c) => c.clientId);
+    expect(ids).toEqual(["client-A1"]);
+  });
+
+  test("filters out all clients when caller has no actorPrincipalId header (fail-closed)", () => {
+    registerClient({ clientId: "client-A1", actorPrincipalId: "user-A" });
+
+    const handler = findHandler("list_clients");
+    const result = handler({}) as ListClientsResponse;
+
+    expect(result.clients).toEqual([]);
+  });
+
+  test("dev-bypass mode returns all clients regardless of actor", () => {
+    fakeHttpAuthDisabled = true;
+    registerClient({ clientId: "client-A1", actorPrincipalId: "user-A" });
+    registerClient({ clientId: "client-B1", actorPrincipalId: "user-B" });
+    registerClient({
+      clientId: "client-noprincipal",
+      actorPrincipalId: undefined,
+    });
+
+    const handler = findHandler("list_clients");
+    const result = handler({
+      headers: { "x-vellum-actor-principal-id": "user-A" },
+    }) as ListClientsResponse;
+
+    const ids = result.clients.map((c) => c.clientId).sort();
+    expect(ids).toEqual(["client-A1", "client-B1", "client-noprincipal"]);
+  });
+});