@vellumai/assistant 0.7.0 → 0.7.1

package/src/runtime/client-registry.ts

@@ -1,254 +0,0 @@
-/**
- * Unified registry of active client connections.
- *
- * Tracks all clients currently connected to the assistant — macOS desktop
- * (SSE), iOS (SSE), web (SSE), chrome-extension (WebSocket), CLI, and
- * channel interfaces. Each entry records the interface type, derived
- * capabilities, and connection timestamps.
- *
- * The registry is populated by:
- *   - SSE /events route (events-routes.ts) — registers on connect,
- *     unregisters on disconnect, touches on heartbeat.
- *
- * Future enhancements:
- *   - Surface ChromeExtensionRegistry entries through `listAll()`
- *
- * Consumers:
- *   - `assistant clients list` CLI command (via `list_clients` IPC route)
- *   - Future: deferred host tool routing (Phase 2)
- */
-
-import type { HostProxyCapability, InterfaceId } from "../channels/types.js";
-import { supportsHostProxy } from "../channels/types.js";
-import { getLogger } from "../util/logger.js";
-
-const log = getLogger("client-registry");
-
-/**
- * Default staleness threshold: entries not refreshed within this window are
- * evicted on the next read. 30 minutes is generous — messages refresh the
- * entry on every turn, so any actively used client stays well within this.
- */
-const DEFAULT_STALE_AGE_MS = 30 * 60 * 1000;
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/** All host-proxy capabilities checked against each interface on register. */
-const ALL_CAPABILITIES: HostProxyCapability[] = [
-  "host_bash",
-  "host_file",
-  "host_cu",
-  "host_browser",
-];
-
-export interface ClientEntry {
-  /** Stable identifier for this client connection. */
-  clientId: string;
-  /** Interface type (e.g. "macos", "ios", "web", "chrome-extension"). */
-  interfaceId: InterfaceId;
-  /** Host-proxy capabilities this client supports. */
-  capabilities: HostProxyCapability[];
-  /** Wall-clock timestamp (ms) when the client first connected. */
-  connectedAt: number;
-  /** Wall-clock timestamp (ms) of the most recent activity. */
-  lastActiveAt: number;
-}
-
-/** Serialized form returned by the IPC route / CLI command. */
-export interface ClientEntryJSON {
-  clientId: string;
-  interfaceId: InterfaceId;
-  capabilities: HostProxyCapability[];
-  connectedAt: string;
-  lastActiveAt: string;
-}
-
-// ---------------------------------------------------------------------------
-// Registry
-// ---------------------------------------------------------------------------
-
-export class ClientRegistry {
-  private clients = new Map<string, ClientEntry>();
-
-  /**
-   * Register or refresh a client connection.
-   *
-   * If a client with the same `clientId` already exists, its `lastActiveAt`
-   * is updated. Otherwise a new entry is created with derived capabilities.
-   */
-  register(opts: { clientId: string; interfaceId: InterfaceId }): ClientEntry {
-    const existing = this.clients.get(opts.clientId);
-    const now = Date.now();
-
-    if (existing) {
-      existing.lastActiveAt = now;
-      log.debug(
-        { clientId: opts.clientId, interfaceId: opts.interfaceId },
-        "client refreshed",
-      );
-      return existing;
-    }
-
-    const capabilities = ALL_CAPABILITIES.filter((cap) =>
-      supportsHostProxy(opts.interfaceId, cap),
-    );
-
-    const entry: ClientEntry = {
-      clientId: opts.clientId,
-      interfaceId: opts.interfaceId,
-      capabilities,
-      connectedAt: now,
-      lastActiveAt: now,
-    };
-
-    this.clients.set(opts.clientId, entry);
-    log.info(
-      {
-        clientId: opts.clientId,
-        interfaceId: opts.interfaceId,
-        capabilities,
-      },
-      "client registered",
-    );
-    return entry;
-  }
-
-  /**
-   * Remove a client connection. No-op if the clientId is not registered.
-   */
-  unregister(clientId: string): void {
-    const entry = this.clients.get(clientId);
-    if (!entry) return;
-    this.clients.delete(clientId);
-    log.info(
-      { clientId, interfaceId: entry.interfaceId },
-      "client unregistered",
-    );
-  }
-
-  /**
-   * Update `lastActiveAt` for a client without changing other fields.
-   * No-op if the clientId is not registered.
-   */
-  touch(clientId: string): void {
-    const entry = this.clients.get(clientId);
-    if (entry) {
-      entry.lastActiveAt = Date.now();
-    }
-  }
-
-  /**
-   * Return a specific client entry, or `undefined` if not registered.
-   */
-  get(clientId: string): ClientEntry | undefined {
-    return this.clients.get(clientId);
-  }
-
-  /**
-   * Return all registered clients, sorted by `lastActiveAt` descending
-   * (most recently active first). Lazily evicts stale entries before
-   * returning so disconnected clients don't linger indefinitely.
-   */
-  listAll(): ClientEntry[] {
-    this.evictStale();
-    return Array.from(this.clients.values()).sort(
-      (a, b) => b.lastActiveAt - a.lastActiveAt,
-    );
-  }
-
-  /**
-   * Return all registered clients that support the given capability,
-   * sorted by `lastActiveAt` descending.
-   */
-  listByCapability(capability: HostProxyCapability): ClientEntry[] {
-    return this.listAll().filter((e) => e.capabilities.includes(capability));
-  }
-
-  /**
-   * Return the most recently active client that supports the given
-   * capability, or `undefined` if none exists.
-   */
-  getMostRecentByCapability(
-    capability: HostProxyCapability,
-  ): ClientEntry | undefined {
-    return this.listByCapability(capability)[0];
-  }
-
-  /**
-   * Return all registered clients with the given interface type,
-   * sorted by `lastActiveAt` descending.
-   */
-  listByInterface(interfaceId: InterfaceId): ClientEntry[] {
-    return this.listAll().filter((e) => e.interfaceId === interfaceId);
-  }
-
-  /**
-   * Return the most recently active client with the given interface type,
-   * or `undefined` if none exists.
-   */
-  getMostRecentByInterface(interfaceId: InterfaceId): ClientEntry | undefined {
-    return this.listByInterface(interfaceId)[0];
-  }
-
-  /**
-   * Remove entries whose `lastActiveAt` is older than `maxAgeMs`.
-   * Called lazily before reads to prevent unbounded map growth from
-   * churning client IDs that are never explicitly unregistered.
-   *
-   * @returns Number of evicted entries.
-   */
-  evictStale(maxAgeMs: number = DEFAULT_STALE_AGE_MS): number {
-    const cutoff = Date.now() - maxAgeMs;
-    let evicted = 0;
-    for (const [id, entry] of this.clients) {
-      if (entry.lastActiveAt < cutoff) {
-        this.clients.delete(id);
-        evicted++;
-        log.debug(
-          { clientId: id, interfaceId: entry.interfaceId },
-          "client evicted (stale)",
-        );
-      }
-    }
-    return evicted;
-  }
-
-  /**
-   * Number of currently registered clients.
-   */
-  get size(): number {
-    return this.clients.size;
-  }
-
-  /**
-   * Serialize a client entry to JSON (ISO timestamps).
-   */
-  static toJSON(entry: ClientEntry): ClientEntryJSON {
-    return {
-      clientId: entry.clientId,
-      interfaceId: entry.interfaceId,
-      capabilities: entry.capabilities,
-      connectedAt: new Date(entry.connectedAt).toISOString(),
-      lastActiveAt: new Date(entry.lastActiveAt).toISOString(),
-    };
-  }
-}
-
-// ── Module-level singleton ────────────────────────────────────────────────
-
-let instance: ClientRegistry | null = null;
-
-export function getClientRegistry(): ClientRegistry {
-  if (!instance) instance = new ClientRegistry();
-  return instance;
-}
-
-/**
- * Test helper: reset the module-level singleton so each test starts with a
- * fresh registry.
- */
-export function __resetClientRegistryForTests(): void {
-  instance = null;
-}

package/src/runtime/routes/inbound-stages/verification-intercept.ts

@@ -1,329 +0,0 @@
-/**
- * Verification code intercept stage: validates and consumes verification
- * codes, applies role-specific side effects (guardian binding creation,
- * trusted-contact activation signals), upserts member records, and delivers
- * deterministic template-driven replies.
- *
- * This is the dispatch point for channel-based post-verification side
- * effects. Voice verification has its own dispatch in relay-server.ts.
- * Both guardian and trusted-contact flows converge here after
- * validateAndConsumeVerification() returns success.
- *
- * Verification code messages are short-circuited here and NEVER enter the
- * agent pipeline. This prevents verification codes from producing
- * agent-generated copy.
- */
-import type { ChannelId } from "../../../channels/types.js";
-import { findContactChannel } from "../../../contacts/contact-store.js";
-import {
-  createGuardianBinding,
-  revokeGuardianBinding,
-  upsertContactChannel,
-} from "../../../contacts/contacts-write.js";
-import {
-  clearPendingVerificationReply,
-  storePendingVerificationReply,
-} from "../../../memory/delivery-channels.js";
-import { emitNotificationSignal } from "../../../notifications/emit-signal.js";
-import type { NotificationSourceChannel } from "../../../notifications/signal.js";
-import { canonicalizeInboundIdentity } from "../../../util/canonicalize-identity.js";
-import { getLogger } from "../../../util/logger.js";
-import {
-  findActiveSession,
-  getGuardianBinding,
-  getPendingSession,
-  validateAndConsumeVerification,
-} from "../../channel-verification-service.js";
-import { deliverChannelReply } from "../../gateway-client.js";
-import {
-  composeChannelVerifyReply,
-  GUARDIAN_VERIFY_TEMPLATE_KEYS,
-} from "../../verification-templates.js";
-import { stripVerificationFailurePrefix } from "../channel-route-shared.js";
-
-const log = getLogger("runtime-http");
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-export interface VerificationInterceptParams {
-  isDuplicate: boolean;
-  guardianVerifyCode: string | undefined;
-  rawSenderId: string | undefined;
-  canonicalSenderId: string | null;
-  canonicalAssistantId: string;
-  sourceChannel: ChannelId;
-  conversationExternalId: string;
-  conversationId: string;
-  eventId: string;
-  replyCallbackUrl: string | undefined;
-  assistantId: string;
-  actorDisplayName: string | undefined;
-  actorUsername: string | undefined;
-}
-
-/**
- * Intercept guardian verification codes and handle them deterministically.
- *
- * Bare 6-digit codes are only intercepted when there is actually a
- * pending challenge or active outbound session for this channel.
- * Without this guard, normal 6-digit messages (zip codes, PINs, etc.)
- * would be swallowed by the verification handler and never reach the
- * agent pipeline.
- *
- * Returns a Response if the verification was handled, or null to continue
- * the pipeline.
- */
-export async function handleVerificationIntercept(
-  params: VerificationInterceptParams,
-): Promise<Record<string, unknown> | null> {
-  const {
-    isDuplicate,
-    guardianVerifyCode,
-    rawSenderId,
-    canonicalSenderId,
-    canonicalAssistantId,
-    sourceChannel,
-    conversationExternalId,
-    conversationId,
-    eventId,
-    replyCallbackUrl,
-    assistantId,
-    actorDisplayName,
-    actorUsername,
-  } = params;
-
-  // Only intercept when there is a pending challenge or active outbound session
-  const shouldIntercept =
-    guardianVerifyCode !== undefined &&
-    (!!getPendingSession(sourceChannel) || !!findActiveSession(sourceChannel));
-
-  if (
-    isDuplicate ||
-    !shouldIntercept ||
-    guardianVerifyCode === undefined ||
-    !rawSenderId
-  ) {
-    return null;
-  }
-
-  const verifyResult = validateAndConsumeVerification(
-    sourceChannel,
-    guardianVerifyCode,
-    canonicalSenderId ?? rawSenderId,
-    conversationExternalId,
-    actorUsername,
-    actorDisplayName,
-  );
-
-  const guardianVerifyOutcome: "verified" | "failed" = verifyResult.success
-    ? "verified"
-    : "failed";
-
-  if (verifyResult.success) {
-    const existingContactResult =
-      (canonicalSenderId ?? rawSenderId)
-        ? findContactChannel({
-            channelType: sourceChannel,
-            externalUserId: canonicalSenderId ?? rawSenderId,
-            externalChatId: conversationExternalId,
-          })
-        : null;
-    const existingChannel = existingContactResult?.channel ?? null;
-    const existingContact = existingContactResult?.contact ?? null;
-    const memberMatchesSender = existingChannel?.externalUserId
-      ? canonicalizeInboundIdentity(
-          sourceChannel,
-          existingChannel.externalUserId,
-        ) === (canonicalSenderId ?? rawSenderId)
-      : false;
-    const preservedDisplayName =
-      memberMatchesSender && existingContact?.displayName?.trim().length
-        ? existingContact.displayName
-        : actorDisplayName;
-
-    upsertContactChannel({
-      sourceChannel,
-      externalUserId: canonicalSenderId ?? rawSenderId,
-      externalChatId: conversationExternalId,
-      status: "active",
-      policy: "allow",
-      // Keep guardian-curated member name stable across re-verification.
-      displayName: preservedDisplayName,
-      username: actorUsername,
-    });
-
-    // Guardian-specific side effect: create/update the guardian binding.
-    // This was previously inside validateAndConsumeVerification but is now
-    // handled here so both verification types have symmetric dispatch.
-    if (verifyResult.verificationType === "guardian") {
-      // Reject if a different user already holds the guardian binding
-      const existingBinding = getGuardianBinding(
-        canonicalAssistantId,
-        sourceChannel,
-      );
-      if (
-        existingBinding &&
-        existingBinding.guardianExternalUserId !==
-          (canonicalSenderId ?? rawSenderId)
-      ) {
-        // Edge case: another user already bound. Log and skip binding creation.
-        // The upsertContactChannel above already succeeded, so the sender is a known contact,
-        // but they won't get guardian role.
-        log.warn(
-          {
-            sourceChannel,
-            existingGuardian: existingBinding.guardianExternalUserId,
-          },
-          "Guardian binding conflict: another user already holds this channel binding",
-        );
-      } else {
-        // Revoke any existing active binding before creating a new one (same-user re-verification)
-        revokeGuardianBinding(sourceChannel);
-
-        const metadata: Record<string, string> = {};
-        if (actorUsername && actorUsername.trim().length > 0) {
-          metadata.username = actorUsername.trim();
-        }
-        if (actorDisplayName && actorDisplayName.trim().length > 0) {
-          metadata.displayName = actorDisplayName.trim();
-        }
-
-        // Unify all channel bindings onto the canonical (vellum) principal
-        const vellumBinding = getGuardianBinding(
-          canonicalAssistantId,
-          "vellum",
-        );
-        const canonicalPrincipal =
-          vellumBinding?.guardianPrincipalId ??
-          canonicalSenderId ??
-          rawSenderId;
-
-        createGuardianBinding({
-          channel: sourceChannel,
-          guardianExternalUserId: canonicalSenderId ?? rawSenderId,
-          guardianDeliveryChatId: conversationExternalId,
-          guardianPrincipalId: canonicalPrincipal,
-          verifiedVia: "challenge",
-          metadataJson:
-            Object.keys(metadata).length > 0 ? JSON.stringify(metadata) : null,
-        });
-      }
-    }
-
-    const verifyLogLabel =
-      verifyResult.verificationType === "trusted_contact"
-        ? "Trusted contact verified"
-        : "Guardian verified";
-    log.info(
-      {
-        sourceChannel,
-        externalUserId: canonicalSenderId,
-        verificationType: verifyResult.verificationType,
-      },
-      `${verifyLogLabel}: auto-upserted ingress member`,
-    );
-
-    // Emit activated signal when a trusted contact completes verification.
-    // Member record is persisted above before this event fires, satisfying
-    // the persistence-before-event ordering invariant.
-    if (verifyResult.verificationType === "trusted_contact") {
-      void emitNotificationSignal({
-        sourceEventName: "ingress.trusted_contact.activated",
-        sourceChannel: sourceChannel as NotificationSourceChannel,
-        sourceContextId: conversationId,
-        attentionHints: {
-          requiresAction: false,
-          urgency: "low",
-          isAsyncBackground: false,
-          visibleInSourceNow: false,
-        },
-        contextPayload: {
-          sourceChannel,
-          actorExternalId: canonicalSenderId ?? rawSenderId,
-          conversationExternalId,
-          actorDisplayName: actorDisplayName ?? null,
-          actorUsername: actorUsername ?? null,
-        },
-        dedupeKey: `trusted-contact:activated:${canonicalAssistantId}:${sourceChannel}:${
-          canonicalSenderId ?? rawSenderId
-        }`,
-      });
-    }
-  }
-
-  // Deliver a deterministic template-driven reply and short-circuit.
-  // Verification code messages must never produce agent-generated copy.
-  if (replyCallbackUrl) {
-    let replyText: string;
-    if (!verifyResult.success) {
-      replyText = composeChannelVerifyReply(
-        GUARDIAN_VERIFY_TEMPLATE_KEYS.CHANNEL_VERIFY_FAILED,
-        { failureReason: stripVerificationFailurePrefix(verifyResult.reason) },
-      );
-    } else {
-      replyText = composeChannelVerifyReply(
-        GUARDIAN_VERIFY_TEMPLATE_KEYS.CHANNEL_VERIFY_SUCCESS,
-        { verificationType: verifyResult.verificationType },
-      );
-    }
-    try {
-      await deliverChannelReply(replyCallbackUrl, {
-        chatId: conversationExternalId,
-        text: replyText,
-        assistantId,
-      });
-    } catch (err) {
-      // The challenge is already consumed and side effects applied, so
-      // we cannot simply re-throw and let the gateway retry the full
-      // flow. Instead, persist the reply so that gateway retries
-      // (which arrive as duplicates) can re-attempt delivery.
-      log.error(
-        { err, conversationExternalId },
-        "Failed to deliver deterministic verification reply; persisting for retry",
-      );
-      storePendingVerificationReply(eventId, {
-        chatId: conversationExternalId,
-        text: replyText,
-        assistantId,
-      });
-
-      // Self-retry after a short delay. The gateway deduplicates
-      // inbound webhooks after a successful forward, so duplicate
-      // retries may never arrive. This fire-and-forget retry ensures
-      // delivery is re-attempted even without a gateway duplicate.
-      setTimeout(async () => {
-        try {
-          await deliverChannelReply(replyCallbackUrl, {
-            chatId: conversationExternalId,
-            text: replyText,
-            assistantId,
-          });
-          log.info({ eventId }, "Verification reply delivered on self-retry");
-          clearPendingVerificationReply(eventId);
-        } catch (retryErr) {
-          log.error(
-            { err: retryErr, eventId },
-            "Verification reply self-retry also failed; pending reply remains as fallback",
-          );
-        }
-      }, 3000);
-
-      return ({
-        accepted: true,
-        duplicate: false,
-        eventId,
-        verificationOutcome: guardianVerifyOutcome,
-        deliveryPending: true,
-      });
-    }
-  }
-
-  return ({
-    accepted: true,
-    duplicate: false,
-    eventId,
-    verificationOutcome: guardianVerifyOutcome,
-  });
-}