@vellumai/assistant 0.6.5 → 0.7.0

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

@@ -5,11 +5,11 @@
  * submit button decisions without relying on text parsing.
  *
  * All guardian action endpoints require a valid JWT bearer token.
- * Auth is verified upstream by JWT middleware; the AuthContext is
- * threaded through from the HTTP server layer.
+ * Auth is verified upstream by JWT middleware; the adapter injects the
+ * actor principal ID via the `x-vellum-actor-principal-id` header.
  *
  * Guardian decisions additionally verify the actor is the bound guardian
- * via the AuthContext's actorPrincipalId.
+ * via the `requireGuardian` route flag.
  */
 import { z } from "zod";
 
@@ -19,41 +19,24 @@ import {
   type CanonicalGuardianRequest,
   listPendingRequestsByConversationScope,
 } from "../../memory/canonical-guardian-store.js";
-import { isPermissionControlsV2Enabled } from "../../permissions/v2-consent-policy.js";
-import { requireBoundGuardian } from "../auth/require-bound-guardian.js";
-import type { AuthContext } from "../auth/types.js";
 import { processGuardianDecision } from "../guardian-action-service.js";
 import type { GuardianDecisionPrompt } from "../guardian-decision-types.js";
-import {
-  buildDecisionActions,
-  buildOneTimeDecisionActions,
-} from "../guardian-decision-types.js";
-import { httpError } from "../http-errors.js";
-import type { RouteDefinition } from "../http-router.js";
+import { buildOneTimeDecisionActions } from "../guardian-decision-types.js";
+import { BadRequestError, NotFoundError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 // ---------------------------------------------------------------------------
 // GET /v1/guardian-actions/pending?conversationId=...
 // ---------------------------------------------------------------------------
 
-/**
- * List pending guardian decision prompts for a conversation.
- * Auth is verified upstream by JWT middleware.
- *
- * Returns guardian approval requests (from the channel guardian store) that
- * are still pending, mapped to the GuardianDecisionPrompt shape so clients
- * can render structured button UIs.
- */
-export function handleGuardianActionsPending(
-  url: URL,
-  _authContext: AuthContext,
-): Response {
-  const conversationId = url.searchParams.get("conversationId");
+function handleGuardianActionsPending({
+  queryParams = {},
+}: RouteHandlerArgs) {
+  const conversationId = queryParams.conversationId;
 
   if (!conversationId) {
-    return httpError(
-      "BAD_REQUEST",
+    throw new BadRequestError(
       "conversationId query parameter is required",
-      400,
     );
   }
 
@@ -61,63 +44,46 @@ export function handleGuardianActionsPending(
     conversationId,
     channel: "vellum",
   });
-  return Response.json({ conversationId, prompts });
+  return { conversationId, prompts };
 }
 
 // ---------------------------------------------------------------------------
 // POST /v1/guardian-actions/decision
 // ---------------------------------------------------------------------------
 
-/**
- * Submit a guardian action decision.
- * Requires AuthContext with a bound guardian actor.
- *
- * Routes all decisions through the unified canonical guardian decision
- * primitive which handles CAS resolution, resolver dispatch, and grant
- * minting.
- */
-export async function handleGuardianActionDecision(
-  req: Request,
-  authContext: AuthContext,
-): Promise<Response> {
-  const guardianError = requireBoundGuardian(authContext);
-  if (guardianError) return guardianError;
+export async function handleGuardianActionDecision({
+  body,
+  headers = {},
+}: RouteHandlerArgs) {
+  if (!body || typeof body !== "object") {
+    throw new BadRequestError("Request body is required");
+  }
 
-  const body = (await req.json()) as {
+  const { requestId, action, conversationId } = body as {
     requestId?: string;
     action?: string;
     conversationId?: string;
   };
 
-  const { requestId, action, conversationId } = body;
-
   if (!requestId || typeof requestId !== "string") {
-    return httpError("BAD_REQUEST", "requestId is required", 400);
+    throw new BadRequestError("requestId is required");
   }
 
   if (!action || typeof action !== "string") {
-    return httpError("BAD_REQUEST", "action is required", 400);
+    throw new BadRequestError("action is required");
   }
 
+  // Resolve the actor's guardian principal ID. The HTTP adapter injects it
+  // from the AuthContext via the x-vellum-actor-principal-id header.
+  // For dev bypass (HTTP auth disabled) the synthetic "dev-bypass" principal
+  // won't match the real guardian binding, so fall back to the local guardian
+  // binding to avoid identity_mismatch.
+  let guardianPrincipalId: string | undefined =
+    headers["x-vellum-actor-principal-id"] ?? undefined;
   if (
-    isPermissionControlsV2Enabled() &&
-    action !== "approve_once" &&
-    action !== "reject"
+    isHttpAuthDisabled() &&
+    headers["x-vellum-actor-principal-id"] === "dev-bypass"
   ) {
-    return httpError(
-      "FORBIDDEN",
-      "permission-controls-v2 only accepts approve_once or reject for guardian actions",
-      403,
-    );
-  }
-
-  // Resolve the actor's guardian principal ID. For JWT-verified actors this
-  // comes from the token claims. For dev bypass (HTTP auth disabled) the
-  // synthetic "dev-bypass" principal won't match the real guardian binding,
-  // so fall back to the local guardian binding to avoid identity_mismatch.
-  let guardianPrincipalId: string | undefined =
-    authContext.actorPrincipalId ?? undefined;
-  if (isHttpAuthDisabled() && authContext.actorPrincipalId === "dev-bypass") {
     const binding = findGuardianForChannel("vellum");
     guardianPrincipalId = binding?.contact.principalId ?? undefined;
   }
@@ -134,29 +100,28 @@ export async function handleGuardianActionDecision(
   });
 
   if (!result.ok) {
-    return httpError("BAD_REQUEST", result.message, 400);
+    throw new BadRequestError(result.message);
   }
   if (result.applied) {
-    return Response.json({
+    return {
       applied: true,
       requestId: result.requestId,
       ...(result.replyText ? { replyText: result.replyText } : {}),
-    });
+    };
   }
-  return result.reason === "not_found"
-    ? httpError(
-        "NOT_FOUND",
-        "No pending guardian action found for this requestId",
-        404,
-      )
-    : Response.json({
-        applied: false,
-        reason: result.reason,
-        ...(result.resolverFailureReason
-          ? { resolverFailureReason: result.resolverFailureReason }
-          : {}),
-        requestId: result.requestId ?? requestId,
-      });
+  if (result.reason === "not_found") {
+    throw new NotFoundError(
+      "No pending guardian action found for this requestId",
+    );
+  }
+  return {
+    applied: false,
+    reason: result.reason,
+    ...(result.resolverFailureReason
+      ? { resolverFailureReason: result.resolverFailureReason }
+      : {}),
+    requestId: result.requestId ?? requestId,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -202,33 +167,13 @@ export function listGuardianDecisionPrompts(params: {
 // Canonical request -> prompt mapping
 // ---------------------------------------------------------------------------
 
-/**
- * Map a canonical guardian request to the client-facing prompt format.
- *
- * Generates kind-specific questionText and action sets:
- * - `tool_approval`: temporal modes (approve_once, approve_10m, approve_conversation) + reject in legacy mode,
- *   approve_once + reject only under v2
- * - `pending_question`: approve_once + reject only
- * - `access_request`: approve_once + reject only, with text fallback instructions
- *   (request code + "open invite flow")
- * - `tool_grant_request`: approve_once + reject only
- *
- * Under permission-controls-v2 we collapse all deterministic guardian action
- * prompts to approve_once + reject only. Outside v2, only `tool_approval`
- * receives temporal modes because time-scoped grants are meaningful only for
- * tool execution.
- */
 function mapCanonicalRequestToPrompt(
   req: CanonicalGuardianRequest,
   conversationId: string,
 ): GuardianDecisionPrompt {
   const questionText = buildKindAwareQuestionText(req);
 
-  const actions = isPermissionControlsV2Enabled()
-    ? buildOneTimeDecisionActions()
-    : req.kind === "tool_approval"
-      ? buildDecisionActions({ forGuardianOnBehalf: true })
-      : buildOneTimeDecisionActions();
+  const actions = buildOneTimeDecisionActions();
 
   const expiresAt = req.expiresAt
     ? new Date(req.expiresAt).getTime()
@@ -242,9 +187,6 @@ function mapCanonicalRequestToPrompt(
     toolName: req.toolName ?? null,
     actions,
     expiresAt,
-    // Normalize to the queried conversation ID for client rendering stability.
-    // The canonical request's source conversationId may differ from the
-    // guardian destination conversation the client is viewing.
     conversationId,
     callSessionId: req.callSessionId ?? null,
     kind: req.kind,
@@ -255,13 +197,6 @@ function mapCanonicalRequestToPrompt(
   };
 }
 
-/**
- * Build kind-aware question text for the guardian prompt.
- *
- * For `access_request`, appends deterministic text fallback instructions
- * (request-code approve/reject + "open invite flow") so the prompt remains
- * actionable even when buttons are unavailable or not used.
- */
 function buildKindAwareQuestionText(req: CanonicalGuardianRequest): string {
   const baseText =
     req.questionText ??
@@ -287,61 +222,60 @@ function buildKindAwareQuestionText(req: CanonicalGuardianRequest): string {
 }
 
 // ---------------------------------------------------------------------------
-// Route definitions
+// Route definitions (shared HTTP + IPC)
 // ---------------------------------------------------------------------------
 
-export function guardianActionRouteDefinitions(): RouteDefinition[] {
-  return [
-    {
-      endpoint: "guardian-actions/pending",
-      method: "GET",
-      summary: "List pending guardian actions",
-      description:
-        "Return pending guardian decision prompts for a conversation.",
-      tags: ["guardian"],
-      queryParams: [
-        {
-          name: "conversationId",
-          schema: { type: "string" },
-          description: "Conversation ID (required)",
-        },
-      ],
-      responseBody: z.object({
-        conversationId: z.string(),
-        prompts: z
-          .array(z.unknown())
-          .describe("Guardian decision prompt objects"),
-      }),
-      handler: ({ url, authContext }) =>
-        handleGuardianActionsPending(url, authContext),
-    },
-    {
-      endpoint: "guardian-actions/decision",
-      method: "POST",
-      summary: "Submit guardian decision",
-      description: "Submit a guardian action decision (approve/reject).",
-      tags: ["guardian"],
-      requestBody: z.object({
-        requestId: z.string().describe("Guardian request ID"),
-        action: z.string().describe("Decision action"),
-        conversationId: z.string().describe("Conversation ID").optional(),
-      }),
-      responseBody: z.object({
-        applied: z.boolean(),
-        requestId: z.string(),
-        reason: z
-          .string()
-          .optional()
-          .describe("Decline reason (present only when applied is false)"),
-        replyText: z
-          .string()
-          .optional()
-          .describe(
-            "Resolver reply text for the guardian (e.g. verification code)",
-          ),
-      }),
-      handler: async ({ req, authContext }) =>
-        handleGuardianActionDecision(req, authContext),
-    },
-  ];
-}
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "guardian_actions_pending",
+    endpoint: "guardian-actions/pending",
+    method: "GET",
+    summary: "List pending guardian actions",
+    description:
+      "Return pending guardian decision prompts for a conversation.",
+    tags: ["guardian"],
+    queryParams: [
+      {
+        name: "conversationId",
+        schema: { type: "string" },
+        description: "Conversation ID (required)",
+      },
+    ],
+    responseBody: z.object({
+      conversationId: z.string(),
+      prompts: z
+        .array(z.unknown())
+        .describe("Guardian decision prompt objects"),
+    }),
+    handler: handleGuardianActionsPending,
+  },
+  {
+    operationId: "guardian_actions_decision",
+    endpoint: "guardian-actions/decision",
+    method: "POST",
+    requireGuardian: true,
+    summary: "Submit guardian decision",
+    description: "Submit a guardian action decision (approve/reject).",
+    tags: ["guardian"],
+    requestBody: z.object({
+      requestId: z.string().describe("Guardian request ID"),
+      action: z.string().describe("Decision action"),
+      conversationId: z.string().describe("Conversation ID").optional(),
+    }),
+    responseBody: z.object({
+      applied: z.boolean(),
+      requestId: z.string(),
+      reason: z
+        .string()
+        .optional()
+        .describe("Decline reason (present only when applied is false)"),
+      replyText: z
+        .string()
+        .optional()
+        .describe(
+          "Resolver reply text for the guardian (e.g. verification code)",
+        ),
+    }),
+    handler: handleGuardianActionDecision,
+  },
+];

package/src/runtime/routes/guardian-approval-interception.ts

@@ -8,7 +8,7 @@
  */
 import { applyGuardianDecision } from "../../approvals/guardian-decision-primitive.js";
 import type { ChannelId } from "../../channels/types.js";
-import type { TrustContext } from "../../daemon/conversation-runtime-assembly.js";
+import type { TrustContext } from "../../daemon/trust-context.js";
 import {
   getAllPendingApprovalsByGuardianChat,
   getPendingApprovalForRequest,
@@ -63,7 +63,6 @@ export interface ApprovalInterceptionParams {
   sourceChannel: ChannelId;
   actorExternalId?: string;
   replyCallbackUrl: string;
-  bearerToken?: string;
   trustCtx: TrustContext;
   assistantId: string;
   approvalCopyGenerator?: ApprovalCopyGenerator;
@@ -102,7 +101,6 @@ export async function handleApprovalInterception(
     sourceChannel,
     actorExternalId,
     replyCallbackUrl,
-    bearerToken,
     trustCtx,
     assistantId,
     approvalCopyGenerator,
@@ -122,7 +120,6 @@ export async function handleApprovalInterception(
       sourceChannel,
       actorExternalId,
       replyCallbackUrl,
-      bearerToken,
       assistantId,
       approvalCopyGenerator,
       approvalConversationGenerator,
@@ -186,7 +183,7 @@ export async function handleApprovalInterception(
       return { handled: true, type: "stale_ignored" };
     }
 
-    const result = applyGuardianDecision({
+    const result = await applyGuardianDecision({
       approval: guardianPending[0],
       decision: reactionDecision,
       actorPrincipalId: undefined,
@@ -218,7 +215,7 @@ export async function handleApprovalInterception(
     if (pending.length > 0) {
       const reason: "no_identity" | "no_binding" =
         !trustCtx.requesterExternalUserId ? "no_identity" : "no_binding";
-      handleChannelDecision(
+      await handleChannelDecision(
         conversationId,
         { action: "reject", source: "plain_text" },
         buildGuardianDenyContext(pending[0].toolName, reason, sourceChannel),
@@ -283,7 +280,7 @@ export async function handleApprovalInterception(
             };
             // Apply the cancel decision through the unified primitive.
             // The primitive handles record update and (no-op) grant logic.
-            const cancelApplyResult = applyGuardianDecision({
+            const cancelApplyResult = await applyGuardianDecision({
               approval: guardianApprovalForRequest,
               decision: rejectDecision,
               actorPrincipalId: undefined, // Interception path — principal not available
@@ -318,11 +315,7 @@ export async function handleApprovalInterception(
                   cancelPayload.ephemeral = true;
                   cancelPayload.user = requesterEphemeral;
                 }
-                await deliverChannelReply(
-                  replyCallbackUrl,
-                  cancelPayload,
-                  bearerToken,
-                );
+                await deliverChannelReply(replyCallbackUrl, cancelPayload);
               } catch (err) {
                 log.error(
                   { err, conversationId },
@@ -360,7 +353,6 @@ export async function handleApprovalInterception(
                 await deliverChannelReply(
                   replyCallbackUrl,
                   guardianCancelPayload,
-                  bearerToken,
                 );
               } catch (err) {
                 log.error(
@@ -379,7 +371,6 @@ export async function handleApprovalInterception(
               replyCallbackUrl,
               chatId: conversationExternalId,
               assistantId,
-              bearerToken,
               approvalCopyGenerator,
               logger: log,
               errorLogMessage:
@@ -409,11 +400,7 @@ export async function handleApprovalInterception(
                 followupPayload.ephemeral = true;
                 followupPayload.user = followupEphemeral;
               }
-              await deliverChannelReply(
-                replyCallbackUrl,
-                followupPayload,
-                bearerToken,
-              );
+              await deliverChannelReply(replyCallbackUrl, followupPayload);
             } catch (err) {
               log.error(
                 { err, conversationId },
@@ -431,7 +418,6 @@ export async function handleApprovalInterception(
           replyCallbackUrl,
           chatId: conversationExternalId,
           assistantId,
-          bearerToken,
           approvalCopyGenerator,
           logger: log,
           errorLogMessage:
@@ -457,7 +443,7 @@ export async function handleApprovalInterception(
           action: "reject",
           source: "plain_text",
         };
-        handleChannelDecision(conversationId, expiredDecision);
+        await handleChannelDecision(conversationId, expiredDecision);
 
         await deliverStaleApprovalReply({
           scenario: "guardian_expired_requester",
@@ -465,7 +451,6 @@ export async function handleApprovalInterception(
           replyCallbackUrl,
           chatId: conversationExternalId,
           assistantId,
-          bearerToken,
           approvalCopyGenerator,
           logger: log,
           errorLogMessage:
@@ -503,7 +488,6 @@ export async function handleApprovalInterception(
           replyCallbackUrl,
           chatId: conversationExternalId,
           assistantId,
-          bearerToken,
           approvalCopyGenerator,
           logger: log,
           errorLogMessage:
@@ -537,7 +521,10 @@ export async function handleApprovalInterception(
     if (pending.length === 0) {
       return { handled: true, type: "stale_ignored" };
     }
-    const result = handleChannelDecision(conversationId, reactionDecision);
+    const result = await handleChannelDecision(
+      conversationId,
+      reactionDecision,
+    );
     if (result.applied) {
       return { handled: true, type: "decision_applied" };
     }
@@ -570,7 +557,6 @@ export async function handleApprovalInterception(
               chatId: conversationExternalId,
               messageTs: approvalMessageTs,
               assistantId,
-              bearerToken,
               conversationId,
             });
           }
@@ -579,7 +565,7 @@ export async function handleApprovalInterception(
         }
       }
 
-      const result = handleChannelDecision(conversationId, cbDecision);
+      const result = await handleChannelDecision(conversationId, cbDecision);
 
       if (result.applied) {
         // Edit the original Slack approval message to show the decision
@@ -591,16 +577,12 @@ export async function handleApprovalInterception(
             decisionOutcome === "approved" ? "\u2713" : "\u2717";
           const statusLabel =
             decisionOutcome === "approved" ? "Approved" : "Denied";
-          deliverChannelReply(
-            replyCallbackUrl,
-            {
-              chatId: conversationExternalId,
-              text: `${statusEmoji} ${statusLabel}`,
-              messageTs: approvalMessageTs,
-              assistantId,
-            },
-            bearerToken,
-          ).catch((err) => {
+          deliverChannelReply(replyCallbackUrl, {
+            chatId: conversationExternalId,
+            text: `${statusEmoji} ${statusLabel}`,
+            messageTs: approvalMessageTs,
+            assistantId,
+          }).catch((err) => {
             log.error(
               { err, conversationId, messageTs: approvalMessageTs },
               "Failed to edit Slack approval message after decision",
@@ -622,7 +604,6 @@ export async function handleApprovalInterception(
           chatId: conversationExternalId,
           messageTs: approvalMessageTs,
           assistantId,
-          bearerToken,
           conversationId,
         });
       }
@@ -644,7 +625,6 @@ export async function handleApprovalInterception(
       replyCallbackUrl,
       content,
       assistantId,
-      bearerToken,
       approvalCopyGenerator,
       approvalConversationGenerator,
       pending,
@@ -661,15 +641,10 @@ export async function handleApprovalInterception(
     const nlIntent = parseApprovalIntent(content);
     if (nlIntent && nlIntent.confidence >= 0.9) {
       const nlDecision: ApprovalDecisionResult = {
-        action:
-          nlIntent.decision === "approve"
-            ? "approve_once"
-            : nlIntent.decision === "approve_10m"
-              ? "approve_10m"
-              : "reject",
+        action: nlIntent.decision === "approve" ? "approve_once" : "reject",
         source: "plain_text",
       };
-      const nlResult = handleChannelDecision(conversationId, nlDecision);
+      const nlResult = await handleChannelDecision(conversationId, nlDecision);
       if (nlResult.applied) {
         return { handled: true, type: "decision_applied" };
       }
@@ -684,7 +659,6 @@ export async function handleApprovalInterception(
     replyCallbackUrl,
     chatId: conversationExternalId,
     assistantId,
-    bearerToken,
     approvalCopyGenerator,
     logger: log,
     errorLogMessage: "Failed to deliver approval status reply",
@@ -712,7 +686,6 @@ function editStaleSlackApprovalMessage(params: {
   chatId: string;
   messageTs: string;
   assistantId: string;
-  bearerToken?: string;
   conversationId: string;
 }): void {
   const statusText = "This approval request has been resolved.";
@@ -726,17 +699,13 @@ function editStaleSlackApprovalMessage(params: {
       elements: [{ type: "mrkdwn", text: statusText }],
     },
   ];
-  deliverChannelReply(
-    params.replyCallbackUrl,
-    {
-      chatId: params.chatId,
-      text: statusText,
-      blocks,
-      messageTs: params.messageTs,
-      assistantId: params.assistantId,
-    },
-    params.bearerToken,
-  ).catch((err) => {
+  deliverChannelReply(params.replyCallbackUrl, {
+    chatId: params.chatId,
+    text: statusText,
+    blocks,
+    messageTs: params.messageTs,
+    assistantId: params.assistantId,
+  }).catch((err) => {
     log.error(
       {
         err,