@vellumai/assistant 0.4.29 → 0.4.30

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

@@ -9,22 +9,34 @@
  */
 
 import {
+  getAssistantContactMetadata,
+  getChannelById,
   getContact,
   listContacts,
   mergeContacts,
   searchContacts,
   updateChannelStatus,
+  upsertAssistantContactMetadata,
   upsertContact,
+  validateSpeciesMetadata,
 } from "../../contacts/contact-store.js";
 import type {
+  AssistantSpecies,
   ChannelPolicy,
   ChannelStatus,
   ContactRole,
+  ContactType,
 } from "../../contacts/types.js";
 import { httpError } from "../http-errors.js";
 
+const VALID_CONTACT_TYPES: readonly ContactType[] = ["human", "assistant"];
+const VALID_ASSISTANT_SPECIES: readonly AssistantSpecies[] = [
+  "vellum",
+  "openclaw",
+];
+
 /**
- * GET /v1/contacts?limit=50&role=guardian
+ * GET /v1/contacts?limit=50&role=guardian&contactType=human
  *
  * Also supports search query params: query, channelAddress, channelType, relationship.
  * When any search param is provided, delegates to searchContacts() instead of listContacts().
@@ -32,12 +44,26 @@ import { httpError } from "../http-errors.js";
 export function handleListContacts(url: URL, assistantId: string): Response {
   const limit = Number(url.searchParams.get("limit") ?? 50);
   const role = url.searchParams.get("role") as ContactRole | null;
+  const contactTypeParam = url.searchParams.get("contactType");
   const query = url.searchParams.get("query");
   const channelAddress = url.searchParams.get("channelAddress");
   const channelType = url.searchParams.get("channelType");
   const relationship = url.searchParams.get("relationship");
 
-  const hasSearchParams = query || channelAddress || relationship;
+  if (contactTypeParam && !isContactType(contactTypeParam)) {
+    return httpError(
+      "BAD_REQUEST",
+      `Invalid contactType "${contactTypeParam}". Must be one of: ${VALID_CONTACT_TYPES.join(", ")}`,
+      400,
+    );
+  }
+
+  const hasSearchParams =
+    query || channelAddress || channelType || relationship;
+
+  const contactType = contactTypeParam
+    ? (contactTypeParam as ContactType)
+    : undefined;
 
   if (hasSearchParams) {
     const contacts = searchContacts({
@@ -46,12 +72,19 @@ export function handleListContacts(url: URL, assistantId: string): Response {
       channelAddress: channelAddress ?? undefined,
       channelType: channelType ?? undefined,
       relationship: relationship ?? undefined,
+      role: role ?? undefined,
+      contactType,
       limit,
     });
     return Response.json({ ok: true, contacts });
   }
 
-  const contacts = listContacts(assistantId, limit, role ?? undefined);
+  const contacts = listContacts(
+    assistantId,
+    limit,
+    role ?? undefined,
+    contactType,
+  );
   return Response.json({ ok: true, contacts });
 }
 
@@ -66,7 +99,15 @@ export function handleGetContact(
   if (!contact) {
     return httpError("NOT_FOUND", `Contact "${contactId}" not found`, 404);
   }
-  return Response.json({ ok: true, contact });
+  const assistantMeta =
+    contact.contactType === "assistant"
+      ? getAssistantContactMetadata(contact.id)
+      : undefined;
+  return Response.json({
+    ok: true,
+    contact,
+    assistantMetadata: assistantMeta ?? undefined,
+  });
 }
 
 /**
@@ -91,8 +132,37 @@ export async function handleMergeContacts(
   }
 }
 
+const VALID_CHANNEL_STATUSES: readonly ChannelStatus[] = [
+  "active",
+  "pending",
+  "revoked",
+  "blocked",
+  "unverified",
+];
+const VALID_CHANNEL_POLICIES: readonly ChannelPolicy[] = [
+  "allow",
+  "deny",
+  "escalate",
+];
+
+function isContactType(value: string): value is ContactType {
+  return (VALID_CONTACT_TYPES as readonly string[]).includes(value);
+}
+
+function isAssistantSpecies(value: string): value is AssistantSpecies {
+  return (VALID_ASSISTANT_SPECIES as readonly string[]).includes(value);
+}
+
+function isChannelStatus(value: string): value is ChannelStatus {
+  return (VALID_CHANNEL_STATUSES as readonly string[]).includes(value);
+}
+
+function isChannelPolicy(value: string): value is ChannelPolicy {
+  return (VALID_CHANNEL_POLICIES as readonly string[]).includes(value);
+}
+
 /**
- * POST /v1/contacts { displayName, id?, relationship?, importance?, ... }
+ * POST /v1/contacts { displayName, id?, relationship?, importance?, contactType?, assistantMetadata?, ... }
  */
 export async function handleUpsertContact(
   req: Request,
@@ -106,7 +176,20 @@ export async function handleUpsertContact(
     responseExpectation?: string;
     preferredTone?: string;
     role?: string;
-    channels?: Array<{ type: string; address: string; isPrimary?: boolean }>;
+    contactType?: string;
+    assistantMetadata?: {
+      species: string;
+      metadata?: Record<string, unknown>;
+    };
+    channels?: Array<{
+      type: string;
+      address: string;
+      isPrimary?: boolean;
+      status?: string;
+      policy?: string;
+      externalUserId?: string;
+      externalChatId?: string;
+    }>;
   };
 
   if (
@@ -135,6 +218,81 @@ export async function handleUpsertContact(
     );
   }
 
+  if (body.contactType !== undefined && !isContactType(body.contactType)) {
+    return httpError(
+      "BAD_REQUEST",
+      `Invalid contactType "${body.contactType}". Must be one of: ${VALID_CONTACT_TYPES.join(", ")}`,
+      400,
+    );
+  }
+
+  if (body.contactType === "assistant") {
+    if (!body.assistantMetadata) {
+      return httpError(
+        "BAD_REQUEST",
+        'assistantMetadata is required when contactType is "assistant"',
+        400,
+      );
+    }
+    if (!isAssistantSpecies(body.assistantMetadata.species)) {
+      return httpError(
+        "BAD_REQUEST",
+        `Invalid species "${body.assistantMetadata.species}". Must be one of: ${VALID_ASSISTANT_SPECIES.join(", ")}`,
+        400,
+      );
+    }
+    try {
+      validateSpeciesMetadata(
+        body.assistantMetadata.species as AssistantSpecies,
+        body.assistantMetadata.metadata ?? null,
+      );
+    } catch (err) {
+      return httpError(
+        "BAD_REQUEST",
+        err instanceof Error ? err.message : String(err),
+        400,
+      );
+    }
+  }
+
+  if (body.contactType === "human" && body.assistantMetadata) {
+    return httpError(
+      "BAD_REQUEST",
+      'assistantMetadata must not be provided when contactType is "human"',
+      400,
+    );
+  }
+
+  if (body.assistantMetadata && !body.contactType) {
+    return httpError(
+      "BAD_REQUEST",
+      'contactType must be "assistant" when assistantMetadata is provided',
+      400,
+    );
+  }
+
+  if (body.channels) {
+    if (!Array.isArray(body.channels)) {
+      return httpError("BAD_REQUEST", "channels must be an array", 400);
+    }
+    for (const ch of body.channels) {
+      if (ch.status !== undefined && !isChannelStatus(ch.status)) {
+        return httpError(
+          "BAD_REQUEST",
+          `Invalid channel status "${ch.status}". Must be one of: ${VALID_CHANNEL_STATUSES.join(", ")}`,
+          400,
+        );
+      }
+      if (ch.policy !== undefined && !isChannelPolicy(ch.policy)) {
+        return httpError(
+          "BAD_REQUEST",
+          `Invalid channel policy "${ch.policy}". Must be one of: ${VALID_CHANNEL_POLICIES.join(", ")}`,
+          400,
+        );
+      }
+    }
+  }
+
   try {
     const contact = upsertContact({
       id: body.id,
@@ -144,9 +302,23 @@ export async function handleUpsertContact(
       responseExpectation: body.responseExpectation,
       preferredTone: body.preferredTone,
       role: body.role as ContactRole | undefined,
+      contactType: body.contactType as ContactType | undefined,
       assistantId,
-      channels: body.channels,
+      channels: body.channels?.map((ch) => ({
+        ...ch,
+        status: ch.status as ChannelStatus | undefined,
+        policy: ch.policy as ChannelPolicy | undefined,
+      })),
     });
+
+    if (body.assistantMetadata) {
+      upsertAssistantContactMetadata({
+        contactId: contact.id,
+        species: body.assistantMetadata.species as AssistantSpecies,
+        metadata: body.assistantMetadata.metadata ?? null,
+      });
+    }
+
     return Response.json(
       { ok: true, contact },
       { status: contact.created ? 201 : 200 },
@@ -157,27 +329,6 @@ export async function handleUpsertContact(
   }
 }
 
-const VALID_CHANNEL_STATUSES: readonly ChannelStatus[] = [
-  "active",
-  "pending",
-  "revoked",
-  "blocked",
-  "unverified",
-];
-const VALID_CHANNEL_POLICIES: readonly ChannelPolicy[] = [
-  "allow",
-  "deny",
-  "escalate",
-];
-
-function isChannelStatus(value: string): value is ChannelStatus {
-  return (VALID_CHANNEL_STATUSES as readonly string[]).includes(value);
-}
-
-function isChannelPolicy(value: string): value is ChannelPolicy {
-  return (VALID_CHANNEL_POLICIES as readonly string[]).includes(value);
-}
-
 /**
  * PATCH /v1/contacts/channels/:channelId { status?, policy?, reason? }
  */
@@ -212,6 +363,23 @@ export async function handleUpdateContactChannel(
     );
   }
 
+  // Blocked-state guard: revoking a blocked channel is not allowed because
+  // blocking is a stronger action than revoking. The caller must explicitly
+  // unblock (set status to "active") before revoking.
+  if (body.status === "revoked") {
+    const existing = getChannelById(channelId);
+    if (!existing) {
+      return httpError("NOT_FOUND", `Channel "${channelId}" not found`, 404);
+    }
+    if (existing.status === "blocked") {
+      return httpError(
+        "CONFLICT",
+        "Cannot revoke a blocked channel. Unblock it first or leave it blocked.",
+        409,
+      );
+    }
+  }
+
   const updated = updateChannelStatus(channelId, {
     status: body.status,
     policy: body.policy,

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

@@ -11,17 +11,13 @@
  * Guardian decisions additionally verify the actor is the bound guardian
  * via the AuthContext's actorPrincipalId.
  */
-import { applyCanonicalGuardianDecision } from "../../approvals/guardian-decision-primitive.js";
-import { isHttpAuthDisabled } from "../../config/env.js";
-import { findGuardianForChannel } from "../../contacts/contact-store.js";
 import {
   type CanonicalGuardianRequest,
-  getCanonicalGuardianRequest,
-  isRequestInConversationScope,
   listPendingRequestsByConversationScope,
 } from "../../memory/canonical-guardian-store.js";
+import { requireBoundGuardian } from "../auth/require-bound-guardian.js";
 import type { AuthContext } from "../auth/types.js";
-import type { ApprovalAction } from "../channel-approval-types.js";
+import { processGuardianDecision } from "../guardian-action-service.js";
 import type { GuardianDecisionPrompt } from "../guardian-decision-types.js";
 import { buildDecisionActions } from "../guardian-decision-types.js";
 import { httpError } from "../http-errors.js";
@@ -63,44 +59,6 @@ export function handleGuardianActionsPending(
 // POST /v1/guardian-actions/decision
 // ---------------------------------------------------------------------------
 
-/**
- * Verify that the actor from AuthContext is the bound guardian for the
- * vellum channel. Returns an error Response if not, or null if allowed.
- */
-function requireBoundGuardian(authContext: AuthContext): Response | null {
-  // Dev bypass: when auth is disabled, skip guardian binding check
-  // (mirrors enforcePolicy dev bypass in route-policy.ts)
-  if (isHttpAuthDisabled()) {
-    return null;
-  }
-  if (!authContext.actorPrincipalId) {
-    return httpError(
-      "FORBIDDEN",
-      "Actor is not the bound guardian for this channel",
-      403,
-    );
-  }
-  const guardianResult = findGuardianForChannel(
-    "vellum",
-    authContext.assistantId,
-  );
-  if (!guardianResult) {
-    // No guardian yet — in pre-bootstrap state, allow through
-    return null;
-  }
-  if (
-    (guardianResult.channel.externalUserId ??
-      guardianResult.contact.principalId) !== authContext.actorPrincipalId
-  ) {
-    return httpError(
-      "FORBIDDEN",
-      "Actor is not the bound guardian for this channel",
-      403,
-    );
-  }
-  return null;
-}
-
 /**
  * Submit a guardian action decision.
  * Requires AuthContext with a bound guardian actor.
@@ -132,77 +90,24 @@ export async function handleGuardianActionDecision(
     return httpError("BAD_REQUEST", "action is required", 400);
   }
 
-  const VALID_ACTIONS = new Set<string>([
-    "approve_once",
-    "approve_10m",
-    "approve_thread",
-    "approve_always",
-    "reject",
-  ]);
-  if (!VALID_ACTIONS.has(action)) {
-    return httpError(
-      "BAD_REQUEST",
-      `Invalid action: ${action}. Must be one of: approve_once, approve_10m, approve_thread, approve_always, reject`,
-      400,
-    );
-  }
-
-  // Verify conversationId scoping before applying the canonical decision.
-  // The decision is allowed when the conversationId matches the request's
-  // source conversation OR a recorded delivery destination conversation.
-  // Channel is scoped to 'vellum' to prevent cross-channel approval when
-  // conversation ID namespaces overlap.
-  if (conversationId) {
-    const canonicalRequest = getCanonicalGuardianRequest(requestId);
-    if (
-      canonicalRequest &&
-      canonicalRequest.conversationId &&
-      !isRequestInConversationScope(requestId, conversationId, "vellum")
-    ) {
-      return httpError(
-        "NOT_FOUND",
-        "No pending guardian action found for this requestId",
-        404,
-      );
-    }
-  }
-
-  // Resolve actor identity from the AuthContext (set by JWT middleware).
-  const actorExternalUserId = authContext.actorPrincipalId ?? undefined;
-  const actorPrincipalId = authContext.actorPrincipalId ?? undefined;
-
-  const canonicalResult = await applyCanonicalGuardianDecision({
+  const result = await processGuardianDecision({
     requestId,
-    action: action as ApprovalAction,
+    action,
+    conversationId,
+    channel: "vellum",
     actorContext: {
-      externalUserId: actorExternalUserId,
-      channel: "vellum",
-      guardianPrincipalId: actorPrincipalId,
+      externalUserId: authContext.actorPrincipalId ?? undefined,
+      guardianPrincipalId: authContext.actorPrincipalId ?? undefined,
     },
-    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: false,
-        reason: "resolver_failed",
-        resolverFailureReason: canonicalResult.resolverFailureReason,
-        requestId: canonicalResult.requestId,
-      });
-    }
-
-    return Response.json({
-      applied: true,
-      requestId: canonicalResult.requestId,
-    });
+  if (!result.ok) {
+    return httpError("BAD_REQUEST", result.message, 400);
   }
-
-  // Return the reason for failure (stale, expired, not_found, etc.)
-  return canonicalResult.reason === "not_found"
+  if (result.applied) {
+    return Response.json({ applied: true, requestId: result.requestId });
+  }
+  return result.reason === "not_found"
     ? httpError(
         "NOT_FOUND",
         "No pending guardian action found for this requestId",
@@ -210,8 +115,11 @@ export async function handleGuardianActionDecision(
       )
     : Response.json({
         applied: false,
-        reason: canonicalResult.reason,
-        requestId,
+        reason: result.reason,
+        ...(result.resolverFailureReason
+          ? { resolverFailureReason: result.resolverFailureReason }
+          : {}),
+        requestId: result.requestId ?? requestId,
       });
 }
 

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

@@ -30,12 +30,14 @@ import type {
   ApprovalConversationGenerator,
   ApprovalCopyGenerator,
 } from "../http-types.js";
+import { parseApprovalIntent } from "../nl-approval-parser.js";
 import { handleGuardianCallbackDecision } from "./approval-strategies/guardian-callback-strategy.js";
 import { handleGuardianLegacyFallback } from "./approval-strategies/guardian-legacy-fallback-strategy.js";
 import { handleGuardianTextEngineDecision } from "./approval-strategies/guardian-text-engine-strategy.js";
 import {
   buildGuardianDenyContext,
   parseCallbackData,
+  parseReactionCallbackData,
 } from "./channel-route-shared.js";
 import { deliverStaleApprovalReply } from "./guardian-approval-reply-helpers.js";
 
@@ -115,6 +117,33 @@ export async function handleApprovalInterception(
     }
   }
 
+  // ── Slack reaction path ──
+  // Reactions produce `callbackData` of the form `reaction:<emoji_name>`.
+  // Handled before the pendingPrompt guard because guardian reactions arrive
+  // on the guardian's chat (guardianChatId), not the requester's conversation,
+  // so getChannelApprovalPrompt(conversationId) would return null.
+  // Only guardians can approve via reaction — non-guardian reactions are
+  // silently ignored to prevent self-approval.
+  if (callbackData?.startsWith("reaction:")) {
+    if (trustCtx.trustClass !== "guardian") {
+      return { handled: true, type: "stale_ignored" };
+    }
+    const reactionDecision = parseReactionCallbackData(callbackData);
+    if (!reactionDecision) {
+      // Unknown emoji — ignore silently
+      return { handled: true, type: "stale_ignored" };
+    }
+    const pending = getApprovalInfoByConversation(conversationId);
+    if (pending.length === 0) {
+      return { handled: true, type: "stale_ignored" };
+    }
+    const result = handleChannelDecision(conversationId, reactionDecision);
+    if (result.applied) {
+      return { handled: true, type: "decision_applied" };
+    }
+    return { handled: true, type: "stale_ignored" };
+  }
+
   // ── Standard approval interception (existing flow) ──
   const pendingPrompt = getChannelApprovalPrompt(conversationId);
   if (!pendingPrompt) return { handled: false };
@@ -394,6 +423,30 @@ export async function handleApprovalInterception(
     }
   }
 
+  // ── Slack reaction path ──
+  // Reactions produce `callbackData` of the form `reaction:<emoji_name>`.
+  // Only guardians can approve via reaction — non-guardian reactions are
+  // silently ignored to prevent self-approval.
+  if (callbackData?.startsWith("reaction:")) {
+    if (trustCtx.trustClass !== "guardian") {
+      return { handled: true, type: "stale_ignored" };
+    }
+    const reactionDecision = parseReactionCallbackData(callbackData);
+    if (!reactionDecision) {
+      // Unknown emoji — ignore silently
+      return { handled: true, type: "stale_ignored" };
+    }
+    const pending = getApprovalInfoByConversation(conversationId);
+    if (pending.length === 0) {
+      return { handled: true, type: "stale_ignored" };
+    }
+    const result = handleChannelDecision(conversationId, reactionDecision);
+    if (result.applied) {
+      return { handled: true, type: "decision_applied" };
+    }
+    return { handled: true, type: "stale_ignored" };
+  }
+
   // Try to extract a decision from callback data (button press) first.
   // Callback/button path remains deterministic and takes priority.
   if (callbackData) {
@@ -451,6 +504,29 @@ export async function handleApprovalInterception(
     });
   }
 
+  // ── Natural language approval intent parser ──
+  // Covers a broad set of colloquial approval/rejection phrases, emoji, and
+  // timed-approval variants. Runs before the legacy parser to provide wider
+  // coverage for channels (like Slack) that rely on plain-text responses.
+  if (pending.length > 0 && content) {
+    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",
+        source: "plain_text",
+      };
+      const nlResult = handleChannelDecision(conversationId, nlDecision);
+      if (nlResult.applied) {
+        return { handled: true, type: "decision_applied" };
+      }
+    }
+  }
+
   // ── Legacy deterministic fallback ──
   // When no conversational engine is available, use the deterministic parser
   // as a safety net for backward compatibility.