@vellumai/assistant 0.3.26 → 0.3.28

package/src/runtime/http-server.ts

@@ -93,6 +93,10 @@ import {
   handleInstructionCall,
   handleStartCall,
 } from './routes/call-routes.js';
+import {
+  startCanonicalGuardianExpirySweep,
+  stopCanonicalGuardianExpirySweep,
+} from './routes/canonical-guardian-expiry-sweep.js';
 import { canonicalChannelAssistantId } from './routes/channel-route-shared.js';
 import {
   handleChannelDeliveryAck,
@@ -341,6 +345,9 @@ export class RuntimeHttpServer {
     startGuardianActionSweep(getGatewayInternalBaseUrl(), this.bearerToken, this.guardianActionCopyGenerator);
     log.info('Guardian action expiry sweep started');
 
+    startCanonicalGuardianExpirySweep();
+    log.info('Canonical guardian request expiry sweep started');
+
     log.info('Running in gateway-only ingress mode. Direct webhook routes disabled.');
     if (!isLoopbackHost(this.hostname)) {
       log.warn('RUNTIME_HTTP_HOST is not bound to loopback. This may expose the runtime to direct public access.');
@@ -361,6 +368,7 @@ export class RuntimeHttpServer {
     this.pairingStore.stop();
     stopGuardianExpirySweep();
     stopGuardianActionSweep();
+    stopCanonicalGuardianExpirySweep();
     if (this.retrySweepTimer) {
       clearInterval(this.retrySweepTimer);
       this.retrySweepTimer = null;

package/src/runtime/routes/canonical-guardian-expiry-sweep.ts

@@ -0,0 +1,116 @@
+/**
+ * Canonical guardian request expiry sweep.
+ *
+ * Periodically scans the `canonical_guardian_requests` table for pending
+ * requests whose `expiresAt` timestamp has passed and transitions them to
+ * the `expired` status.  This ensures that stale requests are cleaned up
+ * even when no follow-up traffic arrives from either the guardian or the
+ * requester.
+ *
+ * Complements the existing sweeps:
+ *   - `calls/guardian-action-sweep.ts` — voice call guardian action expiry
+ *   - `runtime/routes/guardian-expiry-sweep.ts` — channel guardian approval expiry
+ *
+ * Unlike those sweeps, this one operates on the unified canonical domain
+ * (`canonical_guardian_requests`) and does not need to auto-deny pending
+ * interactions or deliver channel notices — the canonical request status
+ * transition is the single source of truth, and consumers (resolvers,
+ * clients polling prompts) observe the expired status directly.
+ */
+
+import {
+  listCanonicalGuardianRequests,
+  resolveCanonicalGuardianRequest,
+} from '../../memory/canonical-guardian-store.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('canonical-guardian-expiry-sweep');
+
+/** Interval at which the expiry sweep runs (60 seconds). */
+const SWEEP_INTERVAL_MS = 60_000;
+
+/** Timer handle for the sweep so it can be stopped in tests and shutdown. */
+let sweepTimer: ReturnType<typeof setInterval> | null = null;
+
+/** Guard against overlapping sweeps. */
+let sweepInProgress = false;
+
+/**
+ * Sweep all pending canonical guardian requests that have expired.
+ *
+ * Uses CAS resolution (`resolveCanonicalGuardianRequest`) so that a
+ * concurrent decision that wins the race is never overwritten by the
+ * sweep.  Returns the count of requests transitioned to expired.
+ */
+export function sweepExpiredCanonicalGuardianRequests(): number {
+  const pending = listCanonicalGuardianRequests({ status: 'pending' });
+  const now = Date.now();
+  let expiredCount = 0;
+
+  for (const request of pending) {
+    if (!request.expiresAt) continue;
+
+    const expiresAtMs = new Date(request.expiresAt).getTime();
+    if (expiresAtMs >= now) continue;
+
+    // CAS resolve: only transition from 'pending' to 'expired'.
+    // If someone resolved it between our read and this write, the CAS
+    // fails harmlessly (returns null) and we skip the request.
+    const resolved = resolveCanonicalGuardianRequest(request.id, 'pending', {
+      status: 'expired',
+    });
+
+    if (resolved) {
+      expiredCount++;
+      log.info(
+        {
+          event: 'canonical_request_expired',
+          requestId: request.id,
+          kind: request.kind,
+          expiresAt: request.expiresAt,
+        },
+        'Expired canonical guardian request via sweep',
+      );
+    }
+  }
+
+  if (expiredCount > 0) {
+    log.info(
+      { event: 'canonical_expiry_sweep_complete', expiredCount },
+      `Canonical guardian expiry sweep: expired ${expiredCount} request(s)`,
+    );
+  }
+
+  return expiredCount;
+}
+
+/**
+ * Start the periodic canonical guardian expiry sweep. Idempotent — calling
+ * it multiple times reuses the same timer.
+ */
+export function startCanonicalGuardianExpirySweep(): void {
+  if (sweepTimer) return;
+  sweepTimer = setInterval(() => {
+    if (sweepInProgress) return;
+    sweepInProgress = true;
+    try {
+      sweepExpiredCanonicalGuardianRequests();
+    } catch (err) {
+      log.error({ err }, 'Canonical guardian expiry sweep failed');
+    } finally {
+      sweepInProgress = false;
+    }
+  }, SWEEP_INTERVAL_MS);
+}
+
+/**
+ * Stop the periodic canonical guardian expiry sweep. Used in tests and
+ * shutdown.
+ */
+export function stopCanonicalGuardianExpirySweep(): void {
+  if (sweepTimer) {
+    clearInterval(sweepTimer);
+    sweepTimer = null;
+  }
+  sweepInProgress = false;
+}

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

@@ -8,6 +8,10 @@ import { CHANNEL_IDS, INTERFACE_IDS, parseChannelId, parseInterfaceId } from '..
 import { mergeToolResults,renderHistoryContent } from '../../daemon/handlers.js';
 import type { ServerMessage } from '../../daemon/ipc-protocol.js';
 import * as attachmentsStore from '../../memory/attachments-store.js';
+import {
+  createCanonicalGuardianRequest,
+  generateCanonicalRequestCode,
+} from '../../memory/canonical-guardian-store.js';
 import {
   getConversationByKey,
   getOrCreateConversation,
@@ -171,6 +175,20 @@ function makeHubPublisher(
           persistentDecisionsAllowed: msg.persistentDecisionsAllowed,
         },
       });
+
+      // Create a canonical guardian request so IPC/HTTP handlers can find it
+      // via applyCanonicalGuardianDecision.
+      createCanonicalGuardianRequest({
+        id: msg.requestId,
+        kind: 'tool_approval',
+        sourceType: 'desktop',
+        sourceChannel: 'vellum',
+        conversationId,
+        toolName: msg.toolName,
+        status: 'pending',
+        requestCode: generateCanonicalRequestCode(),
+        expiresAt: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
+      });
     } else if (msg.type === 'secret_request') {
       pendingInteractions.register(msg.requestId, {
         session,

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

@@ -4,18 +4,18 @@
  * These endpoints let desktop clients fetch pending guardian prompts and
  * submit button decisions without relying on text parsing.
  */
-import { applyGuardianDecision } from '../../approvals/guardian-decision-primitive.js';
 import {
-  getPendingApprovalForRequest,
-  listPendingApprovalRequests,
-} from '../../memory/channel-guardian-store.js';
+  applyCanonicalGuardianDecision,
+} from '../../approvals/guardian-decision-primitive.js';
+import {
+  type CanonicalGuardianRequest,
+  getCanonicalGuardianRequest,
+  listCanonicalGuardianRequests,
+} from '../../memory/canonical-guardian-store.js';
 import type { ApprovalAction } from '../channel-approval-types.js';
-import { handleChannelDecision } from '../channel-approvals.js';
 import type { GuardianDecisionPrompt } from '../guardian-decision-types.js';
 import { buildDecisionActions } from '../guardian-decision-types.js';
 import { httpError } from '../http-errors.js';
-import * as pendingInteractions from '../pending-interactions.js';
-import { handleAccessRequestDecision } from './access-request-decision.js';
 
 // ---------------------------------------------------------------------------
 // GET /v1/guardian-actions/pending?conversationId=...
@@ -47,8 +47,9 @@ export function handleGuardianActionsPending(req: Request): Response {
 /**
  * Submit a guardian action decision.
  *
- * Looks up the guardian approval by requestId and applies the decision
- * through the unified guardian decision primitive.
+ * 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): Promise<Response> {
   const body = await req.json() as {
@@ -72,65 +73,53 @@ export async function handleGuardianActionDecision(req: Request): Promise<Respon
     return httpError('BAD_REQUEST', `Invalid action: ${action}. Must be one of: approve_once, approve_always, reject`, 400);
   }
 
-  // Try the channel guardian approval store first (tool approval prompts)
-  const approval = getPendingApprovalForRequest(requestId);
-  if (approval) {
-    // Enforce conversationId scoping: reject decisions that target the wrong conversation.
-    if (conversationId && conversationId !== approval.conversationId) {
-      return httpError('BAD_REQUEST', 'conversationId does not match the approval', 400);
+  // Verify conversationId scoping before applying the canonical decision.
+  // A caller must not be able to cross-resolve requests from a different conversation.
+  if (conversationId) {
+    const canonicalRequest = getCanonicalGuardianRequest(requestId);
+    if (canonicalRequest && canonicalRequest.conversationId && canonicalRequest.conversationId !== conversationId) {
+      return httpError('NOT_FOUND', 'No pending guardian action found for this requestId', 404);
     }
+  }
 
-    // Access request approvals need a separate decision path — they don't have
-    // pending interactions and use verification sessions instead.
-    if (approval.toolName === 'ingress_access_request') {
-      const mappedAction = action === 'reject' ? 'deny' as const : 'approve' as const;
-      // Use 'desktop' as the actor identity because this endpoint is
-      // unauthenticated — we cannot verify the caller is the assigned
-      // guardian, so we record a generic desktop origin instead of
-      // falsely attributing the decision to guardianExternalUserId.
-      const decisionResult = handleAccessRequestDecision(
-        approval,
-        mappedAction,
-        'desktop',
-      );
+  const canonicalResult = await applyCanonicalGuardianDecision({
+    requestId,
+    action: action as ApprovalAction,
+    actorContext: {
+      externalUserId: undefined,
+      channel: 'vellum',
+      isTrusted: true,
+    },
+    userText: undefined,
+  });
+
+  if (canonicalResult.applied) {
+    // When the CAS committed but the resolver failed, the side effect
+    // (e.g. minting a verification session) did not happen. From the
+    // caller's perspective the decision was not truly applied.
+    if (canonicalResult.resolverFailed) {
       return Response.json({
-        applied: decisionResult.type !== 'stale',
-        requestId,
-        reason: decisionResult.type === 'stale' ? 'stale' : undefined,
-        accessRequestResult: decisionResult,
+        applied: false,
+        reason: 'resolver_failed',
+        resolverFailureReason: canonicalResult.resolverFailureReason,
+        requestId: canonicalResult.requestId,
       });
     }
 
-    // Note: actorExternalUserId is left undefined because the desktop endpoint
-    // does not authenticate caller identity. This means scoped grant minting is
-    // skipped for button-based decisions — an acceptable trade-off to avoid
-    // falsifying audit records with an unverified guardian identity.
-    const result = applyGuardianDecision({
-      approval,
-      decision: { action: action as 'approve_once' | 'approve_always' | 'reject', source: 'plain_text', requestId },
-      actorExternalUserId: undefined,
-      actorChannel: 'vellum',
+    return Response.json({
+      applied: true,
+      requestId: canonicalResult.requestId,
     });
-    return Response.json({ ...result, requestId: result.requestId ?? requestId });
   }
 
-  // Fall back to the pending interactions tracker (direct confirmation requests).
-  // Route through handleChannelDecision so approve_always properly persists trust rules.
-  const interaction = pendingInteractions.get(requestId);
-  if (interaction) {
-    // Enforce conversationId scoping for interactions too.
-    if (conversationId && conversationId !== interaction.conversationId) {
-      return httpError('BAD_REQUEST', 'conversationId does not match the interaction', 400);
-    }
-
-    const result = handleChannelDecision(
-      interaction.conversationId,
-      { action: action as ApprovalAction, source: 'plain_text', requestId },
-    );
-    return Response.json({ ...result, requestId: result.requestId ?? requestId });
-  }
-
-  return httpError('NOT_FOUND', 'No pending guardian action found for this requestId', 404);
+  // Return the reason for failure (stale, expired, not_found, etc.)
+  return canonicalResult.reason === 'not_found'
+    ? httpError('NOT_FOUND', 'No pending guardian action found for this requestId', 404)
+    : Response.json({
+        applied: false,
+        reason: canonicalResult.reason,
+        requestId,
+      });
 }
 
 // ---------------------------------------------------------------------------
@@ -140,10 +129,9 @@ export async function handleGuardianActionDecision(req: Request): Promise<Respon
 /**
  * Build a list of GuardianDecisionPrompt objects for the given conversation.
  *
- * Aggregates pending guardian approval requests from the channel guardian
- * store and pending confirmation interactions from the pending-interactions
- * tracker, exposing them in a uniform shape that clients can render as
- * structured button UIs.
+ * Reads exclusively from the canonical guardian requests store. All request
+ * kinds (tool_approval, pending_question, access_request, etc.) that have
+ * been created as canonical requests will appear here.
  */
 export function listGuardianDecisionPrompts(params: {
   conversationId: string;
@@ -151,56 +139,59 @@ export function listGuardianDecisionPrompts(params: {
   const { conversationId } = params;
   const prompts: GuardianDecisionPrompt[] = [];
 
-  // 1. Channel guardian approval requests (tool approvals routed to guardians)
-  const approvalRequests = listPendingApprovalRequests({
+  const canonicalRequests = listCanonicalGuardianRequests({
     conversationId,
     status: 'pending',
-  }).filter(a => a.expiresAt > Date.now() && a.requestId != null);
-
-  for (const approval of approvalRequests) {
-    const reqId = approval.requestId!;
-    prompts.push({
-      requestId: reqId,
-      requestCode: reqId.slice(0, 6).toUpperCase(),
-      state: 'pending',
-      questionText: approval.reason ?? `Approve tool: ${approval.toolName ?? 'unknown'}`,
-      toolName: approval.toolName ?? null,
-      actions: buildDecisionActions({ forGuardianOnBehalf: true }),
-      expiresAt: approval.expiresAt,
-      conversationId: approval.conversationId,
-      callSessionId: null,
-    });
-  }
+  });
 
-  // 2. Guardian action requests (voice call guardian questions) are intentionally
-  // excluded here — resolving them requires the answerCall + resolveGuardianActionRequest
-  // flow which is handled by the conversational session-process path, not by the
-  // deterministic button decision endpoint.
-  // TODO: Surface voice guardian-action requests as read-only informational prompts
-  // so desktop clients can see them even though they can't be resolved via buttons.
-
-  // 3. Pending confirmation interactions (direct tool approval prompts)
-  const interactions = pendingInteractions.getByConversation(conversationId);
-  for (const interaction of interactions) {
-    if (interaction.kind !== 'confirmation' || !interaction.confirmationDetails) continue;
-    // Skip if already covered by a channel guardian approval above
-    if (prompts.some(p => p.requestId === interaction.requestId)) continue;
-
-    const details = interaction.confirmationDetails;
-    prompts.push({
-      requestId: interaction.requestId,
-      requestCode: interaction.requestId.slice(0, 6).toUpperCase(),
-      state: 'pending',
-      questionText: `Approve tool: ${details.toolName}`,
-      toolName: details.toolName,
-      actions: buildDecisionActions({
-        persistentDecisionsAllowed: details.persistentDecisionsAllowed,
-      }),
-      expiresAt: Date.now() + 300_000,
-      conversationId,
-      callSessionId: null,
-    });
+  for (const req of canonicalRequests) {
+    // Skip expired canonical requests
+    if (req.expiresAt && new Date(req.expiresAt).getTime() < Date.now()) continue;
+
+    const prompt = mapCanonicalRequestToPrompt(req, conversationId);
+    prompts.push(prompt);
   }
 
   return prompts;
 }
+
+// ---------------------------------------------------------------------------
+// Canonical request -> prompt mapping
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a canonical guardian request to the client-facing prompt format.
+ *
+ * Generates an appropriate questionText based on the request kind, and
+ * determines which actions are available. Pending questions surface as
+ * informational prompts since they may require text input rather than
+ * simple approve/reject buttons.
+ */
+function mapCanonicalRequestToPrompt(
+  req: CanonicalGuardianRequest,
+  conversationId: string,
+): GuardianDecisionPrompt {
+  const questionText = req.questionText
+    ?? (req.toolName ? `Approve tool: ${req.toolName}` : `Guardian request: ${req.kind}`);
+
+  // pending_question requests are typically voice-originated and need
+  // approve/reject only (no approve_always — guardian-on-behalf invariant).
+  const actions = buildDecisionActions({ forGuardianOnBehalf: true });
+
+  const expiresAt = req.expiresAt
+    ? new Date(req.expiresAt).getTime()
+    : Date.now() + 300_000;
+
+  return {
+    requestId: req.id,
+    requestCode: req.requestCode ?? req.id.slice(0, 6).toUpperCase(),
+    state: 'pending',
+    questionText,
+    toolName: req.toolName ?? null,
+    actions,
+    expiresAt,
+    conversationId: req.conversationId ?? conversationId,
+    callSessionId: req.callSessionId ?? null,
+    kind: req.kind,
+  };
+}