@vellumai/assistant 0.7.0 → 0.7.2

package/src/runtime/assistant-event.ts

@@ -16,6 +16,7 @@ import type { ServerMessage } from "../daemon/message-protocol.js";
 export {
   formatSseFrame,
   formatSseHeartbeat,
+  formatSseHeartbeatWithData,
 } from "@vellumai/skill-host-contracts";
 
 /** Daemon-side specialization of the generic event envelope. */
@@ -23,13 +24,8 @@ export type AssistantEvent = BaseAssistantEvent<ServerMessage>;
 
 /** Daemon-side wrapper preserving the original `ServerMessage`-typed signature. */
 export function buildAssistantEvent(
-  assistantId: string,
   message: ServerMessage,
   conversationId?: string,
 ): AssistantEvent {
-  return baseBuildAssistantEvent<ServerMessage>(
-    assistantId,
-    message,
-    conversationId,
-  );
+  return baseBuildAssistantEvent<ServerMessage>(message, conversationId);
 }

package/src/runtime/auth/__tests__/middleware.test.ts

@@ -35,12 +35,6 @@ mock.module("../../../config/env.js", () => ({
 
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../../assistant-scope.js";
 import {
-  mintHostBrowserCapability,
-  resetCapabilityTokenSecretForTests,
-  setCapabilityTokenSecretForTests,
-} from "../../capability-tokens.js";
-import {
-  authenticateHostBrowserResultRequest,
   authenticateRequest,
 } from "../middleware.js";
 import { initAuthSigningKey, mintToken } from "../token-service.js";
@@ -272,55 +266,20 @@ describe("authenticateRequest", () => {
 });
 
 // ---------------------------------------------------------------------------
-// authenticateHostBrowserResultRequest — capability-token-aware auth for the
-// /v1/host-browser-result POST route. Verifies that both the capability-token
-// and JWT paths are accepted, and that a garbage bearer falls through to the
-// JWT path and emits a 401 like any other invalid token.
+// /v1/host-browser-result auth — exercises authenticateRequest with the
+// same request shape the chrome extension sends. Validates that standard
+// JWT auth applies after the capability-token system was removed.
 // ---------------------------------------------------------------------------
 
-describe("authenticateHostBrowserResultRequest", () => {
-  const CAPABILITY_SECRET = Buffer.alloc(32, 7);
-
-  beforeEach(() => {
-    // Pin the capability-token HMAC secret so mint/verify agree across
-    // the test run. The module-level secret cache is reset between
-    // tests so dev-bypass flipping doesn't leak stale state.
-    setCapabilityTokenSecretForTests(CAPABILITY_SECRET);
-  });
-
-  afterAll(() => {
-    resetCapabilityTokenSecretForTests();
-  });
-
-  test("accepts a valid capability token and synthesizes an actor AuthContext", async () => {
-    const { token } = mintHostBrowserCapability("guardian-cap-happy");
-    const req = new Request("http://localhost/v1/host-browser-result", {
-      method: "POST",
-      headers: { Authorization: `Bearer ${token}` },
-    });
-
-    const result = await authenticateHostBrowserResultRequest(req);
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.context.principalType).toBe("actor");
-      expect(result.context.assistantId).toBe(DAEMON_INTERNAL_ASSISTANT_ID);
-      expect(result.context.actorPrincipalId).toBe("guardian-cap-happy");
-      expect(result.context.scopeProfile).toBe("actor_client_v1");
-      // The synthetic context must carry the scopes the route policy
-      // requires — otherwise the router would 403 the POST even though
-      // auth succeeded.
-      expect(result.context.scopes.has("approval.write")).toBe(true);
-    }
-  });
-
-  test("accepts a valid daemon-audience JWT (regression for the legacy path)", async () => {
+describe("authenticateRequest for /v1/host-browser-result", () => {
+  test("accepts a valid daemon-audience JWT", async () => {
     const token = mintValidToken({ sub: "actor:self:jwt-principal" });
     const req = new Request("http://localhost/v1/host-browser-result", {
       method: "POST",
       headers: { Authorization: `Bearer ${token}` },
     });
 
-    const result = await authenticateHostBrowserResultRequest(req);
+    const result = await authenticateRequest(req);
     expect(result.ok).toBe(true);
     if (result.ok) {
       expect(result.context.principalType).toBe("actor");
@@ -334,25 +293,21 @@ describe("authenticateHostBrowserResultRequest", () => {
       method: "POST",
     });
 
-    const result = await authenticateHostBrowserResultRequest(req);
+    const result = await authenticateRequest(req);
     expect(result.ok).toBe(false);
     if (!result.ok) {
       expect(result.response.status).toBe(401);
     }
   });
 
-  test("malformed bearer falls through to JWT path and 401s", async () => {
-    // A bearer that is neither a valid capability token (bad HMAC) nor a
-    // parseable JWT must fail the JWT path and return 401. This is the
-    // primary regression guard against someone accidentally making the
-    // capability-token branch "allow-anything" by swallowing
-    // verification failures.
+  test("malformed bearer returns 401", async () => {
+    // A bearer that is not a parseable JWT must return 401.
     const req = new Request("http://localhost/v1/host-browser-result", {
       method: "POST",
       headers: { Authorization: "Bearer not-a-token.xxxxxxxxxxxxx" },
     });
 
-    const result = await authenticateHostBrowserResultRequest(req);
+    const result = await authenticateRequest(req);
     expect(result.ok).toBe(false);
     if (!result.ok) {
       expect(result.response.status).toBe(401);
@@ -366,7 +321,7 @@ describe("authenticateHostBrowserResultRequest", () => {
       method: "POST",
     });
 
-    const result = await authenticateHostBrowserResultRequest(req);
+    const result = await authenticateRequest(req);
     expect(result.ok).toBe(true);
     if (result.ok) {
       // Same synthetic context shape as authenticateRequest's dev

package/src/runtime/auth/context.ts

@@ -61,12 +61,3 @@ export function buildAuthContext(claims: TokenClaims): BuildAuthContextResult {
 
   return { ok: true, context };
 }
-
-/**
- * True when the request was authenticated as the gateway service.
- * Used at endpoints that gate platform-only or trust-mediated behavior
- * on the caller being the gateway rather than an end-user actor.
- */
-export function isServiceGatewayPrincipal(authContext: AuthContext): boolean {
-  return authContext.principalType === "svc_gateway";
-}

package/src/runtime/auth/middleware.ts

@@ -17,7 +17,7 @@
  * Replaces both the legacy bearer shared-secret check and the
  * actor-token HMAC middleware with a single JWT verification path.
  *
- * In dev mode (DISABLE_HTTP_AUTH + VELLUM_UNSAFE_AUTH_BYPASS), JWT
+ * When DISABLE_HTTP_AUTH is set (platform-managed deployments), JWT
  * verification is skipped and a synthetic AuthContext is constructed
  * so downstream code always has a typed context to consume.
  */
@@ -25,7 +25,6 @@
 import { isHttpAuthDisabled } from "../../config/env.js";
 import { getLogger } from "../../util/logger.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
-import { verifyHostBrowserCapability } from "../capability-tokens.js";
 import { extractBearerToken } from "../middleware/auth.js";
 import { buildAuthContext } from "./context.js";
 import { resolveScopeProfile } from "./scopes.js";
@@ -188,99 +187,4 @@ export function authenticateRequest(req: Request): AuthenticateResult {
   return { ok: true, context: contextResult.context };
 }
 
-// ---------------------------------------------------------------------------
-// Capability-token-aware auth for /v1/host-browser-result
-// ---------------------------------------------------------------------------
 
-/**
- * Build a synthetic AuthContext from a verified host_browser capability
- * claim. The resulting context is shaped to look like an
- * `actor_client_v1` actor so downstream route policy (which requires
- * `approval.write`) and `requireBoundGuardian` (which compares
- * `actorPrincipalId` against the bound guardian) both accept it.
- *
- * The capability token already carries its own HMAC-checked expiry, so
- * there is no policy-epoch gate to apply here — we pin `policyEpoch` to
- * `Number.MAX_SAFE_INTEGER` the same way the dev-bypass context does.
- */
-function buildCapabilityAuthContext(guardianId: string): AuthContext {
-  return {
-    subject: `actor:${DAEMON_INTERNAL_ASSISTANT_ID}:${guardianId}`,
-    principalType: "actor",
-    assistantId: DAEMON_INTERNAL_ASSISTANT_ID,
-    actorPrincipalId: guardianId,
-    scopeProfile: "actor_client_v1",
-    scopes: resolveScopeProfile("actor_client_v1"),
-    policyEpoch: Number.MAX_SAFE_INTEGER,
-  };
-}
-
-/**
- * Authenticate a request that is allowed to present either a JWT or a
- * host_browser capability token. This is the auth entry point for
- * `/v1/host-browser-result` POST specifically — the chrome extension
- * stores a capability token (minted by the
- * `/v1/browser-extension-pair` flow) rather than a daemon JWT, so the
- * POST fallback used when the `/v1/browser-relay` WebSocket is
- * unavailable would otherwise 401 through the JWT-only
- * `authenticateRequest` path.
- *
- * Order of operations (mirrors `handleBrowserRelayUpgrade`):
- *   1. Extract the bearer token. Missing header → 401.
- *   2. Try `verifyHostBrowserCapability(token)` first. If it succeeds,
- *      derive `guardianId` from the capability claims and synthesize an
- *      AuthContext.
- *   3. Otherwise fall through to the standard JWT path so daemon-minted
- *      JWTs (gateway-proxied or direct) continue to work as a
- *      regression-safe compatibility path.
- *
- * Dev bypass (`isHttpAuthDisabled()`) is honored the same way as
- * `authenticateRequest` — we delegate to it directly to pick up the
- * shared synthetic dev-bypass context.
- */
-export async function authenticateHostBrowserResultRequest(
-  req: Request,
-): Promise<AuthenticateResult> {
-  if (isHttpAuthDisabled()) {
-    return { ok: true, context: buildDevBypassContext() };
-  }
-
-  const rawToken = extractBearerToken(req);
-  if (!rawToken) {
-    log.warn(
-      { reason: "missing_token", path: "/v1/host-browser-result" },
-      "Host browser result auth denied: missing Authorization header",
-    );
-    return {
-      ok: false,
-      response: Response.json(
-        {
-          error: {
-            code: "UNAUTHORIZED",
-            message: "Missing Authorization header",
-          },
-        },
-        { status: 401 },
-      ),
-    };
-  }
-
-  // 1) Capability-token path (self-hosted default). The chrome
-  //    extension presents the token it received from the native
-  //    messaging pair flow. We derive `actorPrincipalId` from the
-  //    capability claims directly — the claims are HMAC-signed by the
-  //    same daemon so there is no cross-tenant risk.
-  const capabilityClaims = await verifyHostBrowserCapability(rawToken);
-  if (capabilityClaims) {
-    return {
-      ok: true,
-      context: buildCapabilityAuthContext(capabilityClaims.guardianId),
-    };
-  }
-
-  // 2) JWT compatibility path. Fall back to the existing daemon/gateway
-  //    JWT verification so cloud callers and any legacy self-hosted
-  //    clients still holding a daemon JWT continue to work. Any 401
-  //    emitted here already includes the JWT-specific reason.
-  return authenticateRequest(req);
-}

package/src/runtime/auth/route-policy.ts

@@ -151,8 +151,11 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
   { endpoint: "confirm", scopes: ["approval.write"] },
   { endpoint: "secret", scopes: ["approval.write"] },
   { endpoint: "trust-rules", scopes: ["approval.write"] },
+  { endpoint: "host-app-control-result", scopes: ["approval.write"] },
   { endpoint: "host-bash-result", scopes: ["approval.write"] },
   { endpoint: "host-browser-result", scopes: ["approval.write"] },
+  { endpoint: "host-browser-event", scopes: ["approval.write"] },
+  { endpoint: "host-browser-session-invalidated", scopes: ["approval.write"] },
   { endpoint: "host-cu-result", scopes: ["approval.write"] },
   { endpoint: "host-file-result", scopes: ["approval.write"] },
   { endpoint: "host-transfer-result", scopes: ["approval.write"] },
@@ -204,6 +207,8 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
   { endpoint: "contacts/invites:POST", scopes: ["settings.write"] },
   { endpoint: "contacts/invites/redeem", scopes: ["settings.write"] },
   { endpoint: "contacts/invites:DELETE", scopes: ["settings.write"] },
+  { endpoint: "contacts/prompt:POST", scopes: ["settings.write"] },
+  { endpoint: "resolve_contact_prompt:POST", scopes: ["settings.write"] },
   { endpoint: "integrations/telegram/config", scopes: ["settings.read"] },
   { endpoint: "integrations/telegram/config:POST", scopes: ["settings.write"] },
   {
@@ -221,10 +226,6 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
     endpoint: "integrations/slack/channel/config:DELETE",
     scopes: ["settings.write"],
   },
-  {
-    endpoint: "integrations/slack/channel/oauth-install:POST",
-    scopes: ["settings.write"],
-  },
   { endpoint: "channel-verification-sessions", scopes: ["settings.write"] },
   {
     endpoint: "channel-verification-sessions:DELETE",
@@ -317,12 +318,14 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
   { endpoint: "usage/totals", scopes: ["settings.read"] },
   { endpoint: "usage/daily", scopes: ["settings.read"] },
   { endpoint: "usage/breakdown", scopes: ["settings.read"] },
+  { endpoint: "usage/series", scopes: ["settings.read"] },
 
   // Lifecycle telemetry
   { endpoint: "telemetry/lifecycle", scopes: ["settings.write"] },
 
   // Debug / introspection
   { endpoint: "clients", scopes: ["settings.read"] },
+  { endpoint: "clients/disconnect", scopes: ["settings.write"] },
   { endpoint: "debug", scopes: ["settings.read"] },
 
   // Workspace file browsing
@@ -376,6 +379,9 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
   { endpoint: "config:GET", scopes: ["settings.read"] },
   { endpoint: "config:PATCH", scopes: ["settings.write"] },
 
+  // LLM call site catalog
+  { endpoint: "config/llm/call-sites:GET", scopes: ["settings.read"] },
+
   // Conversation management
   { endpoint: "conversations:DELETE", scopes: ["chat.write"] },
   { endpoint: "conversations/wipe", scopes: ["chat.write"] },
@@ -421,13 +427,18 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
   { endpoint: "memory-items:DELETE", scopes: ["settings.write"] },
   { endpoint: "memory/v2/backfill:POST", scopes: ["settings.write"] },
   { endpoint: "memory/v2/validate:POST", scopes: ["settings.read"] },
+  { endpoint: "memory/v2/concept-page:POST", scopes: ["settings.read"] },
   { endpoint: "memory/v2/reembed-skills:POST", scopes: ["settings.write"] },
+  { endpoint: "memory/v2/explain-similarity:POST", scopes: ["settings.read"] },
+  { endpoint: "memory/v2/fit-anisotropy:POST", scopes: ["settings.write"] },
+  {
+    endpoint: "memory/v2/rebuild-corpus-stats:POST",
+    scopes: ["settings.write"],
+  },
+  { endpoint: "memory/v2/fit-anisotropy:POST", scopes: ["settings.write"] },
 
-  // Trust rule CRUD management
+  // Trust rule listing
   { endpoint: "trust-rules/manage:GET", scopes: ["settings.read"] },
-  { endpoint: "trust-rules/manage:POST", scopes: ["settings.write"] },
-  { endpoint: "trust-rules/manage:DELETE", scopes: ["settings.write"] },
-  { endpoint: "trust-rules/manage:PATCH", scopes: ["settings.write"] },
 
   // Computer use
   { endpoint: "computer-use/sessions", scopes: ["chat.write"] },
@@ -488,6 +499,13 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
   { endpoint: "filing", scopes: ["settings.read"] },
   { endpoint: "filing:POST", scopes: ["settings.write"] },
 
+  // Consolidation (memory v2 counterpart to Filing)
+  { endpoint: "consolidation", scopes: ["settings.read"] },
+  { endpoint: "consolidation:POST", scopes: ["settings.write"] },
+
+  // Gateway log proxy
+  { endpoint: "gateway/logs/tail", scopes: ["settings.read"] },
+
   // Heartbeat (config, runs, checklist — all share the "heartbeat" policyKey)
   { endpoint: "heartbeat:GET", scopes: ["settings.read"] },
   { endpoint: "heartbeat", scopes: ["settings.write"] },
@@ -561,6 +579,9 @@ const INTERNAL_ENDPOINTS = [
   "internal/twilio/status",
   "internal/twilio/connect-action",
   "internal/oauth/callback",
+  "internal/mcp/auth/start",
+  "internal/mcp/auth/status",
+  "internal/mcp/reload",  // ← new
 ];
 for (const endpoint of INTERNAL_ENDPOINTS) {
   registerPolicy(endpoint, {
@@ -699,7 +720,7 @@ registerPolicy("conversations/wipe", {
 
 registerPolicy("trust-rules/suggest", {
   requiredScopes: ["settings.write"],
-  allowedPrincipalTypes: ["local"],
+  allowedPrincipalTypes: ["actor", "svc_gateway", "svc_daemon", "local"],
 });
 
 // Notification pipeline: local-only (CLI / IPC callers)

package/src/runtime/auth/token-service.ts

@@ -215,17 +215,6 @@ export function initAuthSigningKey(key: Buffer): void {
   _authSigningKey = key;
 }
 
-/**
- * Check whether the auth signing key has been initialized.
- *
- * Useful for out-of-process contexts (CLI) that may run without
- * daemon startup, where callers need to decide whether they can
- * mint JWTs or must fall back to the legacy shared-secret token.
- */
-export function isSigningKeyInitialized(): boolean {
-  return _authSigningKey !== undefined;
-}
-
 /**
  * Reset the signing key to undefined. **Test-only** — used to simulate a
  * fresh CLI subprocess where initAuthSigningKey() was never called.

package/src/runtime/btw-sidechain.ts

@@ -1,5 +1,4 @@
 import type { LLMCallSite } from "../config/schemas/llm.js";
-import { buildToolDefinitions } from "../daemon/conversation-tool-setup.js";
 import { buildSystemPrompt } from "../prompts/system-prompt.js";
 import {
   createTimeout,
@@ -27,7 +26,7 @@ export interface RunBtwSidechainParams {
   provider?: Provider;
   messages?: Message[];
   systemPrompt?: string;
-  tools?: ToolDefinition[];
+  tools: ToolDefinition[];
   maxTokens?: number;
   /**
    * Unified call-site identifier. The provider layer resolves
@@ -68,7 +67,7 @@ export async function runBtwSidechain(
     throw new Error("BTW side-chain requires a provider");
   }
 
-  const tools = params.tools ?? buildToolDefinitions();
+  const tools = params.tools;
   const history = params.messages ?? params.conversation?.getMessages() ?? [];
   const messages = [...history, userMessage(trimmedContent)];
   const systemPrompt =

package/src/runtime/channel-approvals.ts

@@ -9,6 +9,7 @@
  *   3. Consume user decisions and apply them to the underlying session
  */
 
+import { findConversation } from "../daemon/conversation-store.js";
 import type { UserDecision } from "../permissions/types.js";
 import { composeApprovalMessage } from "./approval-message-composer.js";
 import type {
@@ -165,13 +166,16 @@ export function handleChannelDecision(
 
   // Map channel-level action to the permission system's UserDecision type.
   const userDecision = mapApprovalActionToUserDecision(decision.action);
+  const conversation = findConversation(resolved.conversationId);
+  if (!conversation) return { applied: false };
+
   if (decisionContext === undefined) {
-    resolved.conversation!.handleConfirmationResponse(
+    conversation.handleConfirmationResponse(
       info.requestId,
       userDecision,
     );
   } else {
-    resolved.conversation!.handleConfirmationResponse(
+    conversation.handleConfirmationResponse(
       info.requestId,
       userDecision,
       undefined,

package/src/runtime/channel-invite-transport.ts

@@ -20,57 +20,11 @@ import { slackInviteAdapter } from "./channel-invite-transports/slack.js";
 import { telegramInviteAdapter } from "./channel-invite-transports/telegram.js";
 import { voiceInviteAdapter } from "./channel-invite-transports/voice.js";
 import { whatsappInviteAdapter } from "./channel-invite-transports/whatsapp.js";
-
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
-
-export interface InviteShareLink {
-  /** The full URL the recipient can open to redeem the invite. */
-  url: string;
-  /** Human-readable text suitable for display alongside the link. */
-  displayText: string;
-}
-
-export interface ChannelInviteAdapter {
-  /** The channel this adapter handles. */
-  channel: ChannelId;
-
-  /**
-   * Build a channel-specific shareable link (e.g. Telegram deep link).
-   * Optional — not all channels support link-based invites.
-   */
-  buildShareLink?(params: {
-    rawToken: string;
-    sourceChannel: ChannelId;
-  }): InviteShareLink;
-
-  /**
-   * Extract a channel-specific invite token from an inbound message
-   * (e.g. Telegram `/start iv_<token>`). Optional — only needed for
-   * channels with link-based invites.
-   */
-  extractInboundToken?(params: {
-    commandIntent?: Record<string, unknown>;
-    content: string;
-    sourceMetadata?: Record<string, unknown>;
-  }): string | undefined;
-
-  /**
-   * Resolve the channel-specific handle to reach the assistant (e.g.
-   * "@botName", "+15551234567", "hello@vellum.me").
-   * Returns `undefined` when the handle cannot be resolved (e.g.
-   * credentials not yet configured).
-   */
-  resolveChannelHandle?(): string | undefined;
-
-  /**
-   * Async variant of `resolveChannelHandle` for adapters that need to
-   * perform I/O (e.g. querying a provider API for the assigned address).
-   * When both are present, `resolveAdapterHandle()` prefers this method.
-   */
-  resolveChannelHandleAsync?(): Promise<string | undefined>;
-}
+import type { ChannelInviteAdapter } from "./channel-invite-types.js";
+export type { ChannelInviteAdapter, InviteShareLink } from "./channel-invite-types.js";
 
 // ---------------------------------------------------------------------------
 // Registry

package/src/runtime/channel-invite-transports/email.ts

@@ -12,7 +12,7 @@
  */
 
 import { getNestedValue, loadRawConfig } from "../../config/loader.js";
-import type { ChannelInviteAdapter } from "../channel-invite-transport.js";
+import type { ChannelInviteAdapter } from "../channel-invite-types.js";
 
 // ---------------------------------------------------------------------------
 // Adapter implementation

package/src/runtime/channel-invite-transports/slack.ts

@@ -9,7 +9,7 @@
 
 import type { ChannelId } from "../../channels/types.js";
 import { getConfig } from "../../config/loader.js";
-import type { ChannelInviteAdapter } from "../channel-invite-transport.js";
+import type { ChannelInviteAdapter } from "../channel-invite-types.js";
 
 // ---------------------------------------------------------------------------
 // Slack bot info resolution

package/src/runtime/channel-invite-transports/telegram.ts

@@ -26,7 +26,7 @@ import { getLogger } from "../../util/logger.js";
 import type {
   ChannelInviteAdapter,
   InviteShareLink,
-} from "../channel-invite-transport.js";
+} from "../channel-invite-types.js";
 
 // ---------------------------------------------------------------------------
 // Bot username resolution

package/src/runtime/channel-invite-transports/voice.ts

@@ -15,7 +15,7 @@ import type { ChannelId } from "../../channels/types.js";
 import type {
   ChannelInviteAdapter,
   InviteShareLink,
-} from "../channel-invite-transport.js";
+} from "../channel-invite-types.js";
 
 // ---------------------------------------------------------------------------
 // Adapter implementation

package/src/runtime/channel-invite-transports/whatsapp.ts

@@ -10,7 +10,7 @@
 
 import type { ChannelId } from "../../channels/types.js";
 import { getConfig } from "../../config/loader.js";
-import type { ChannelInviteAdapter } from "../channel-invite-transport.js";
+import type { ChannelInviteAdapter } from "../channel-invite-types.js";
 
 // ---------------------------------------------------------------------------
 // Phone number resolution

package/src/runtime/channel-invite-types.ts

@@ -0,0 +1,54 @@
+/**
+ * Types extracted from channel-invite-transport.ts to break the
+ * transport ↔ channel-invite-transports/* cycles (×5).
+ */
+
+import type { ChannelId } from "../channels/types.js";
+
+export interface InviteShareLink {
+  /** The full URL the recipient can open to redeem the invite. */
+  url: string;
+  /** Human-readable text suitable for display alongside the link. */
+  displayText: string;
+}
+
+export interface ChannelInviteAdapter {
+  /** The channel this adapter handles. */
+  channel: ChannelId;
+
+  /**
+   * Build a channel-specific shareable link (e.g. Telegram deep link).
+   * Optional — not all channels support link-based invites.
+   */
+  buildShareLink?(params: {
+    rawToken: string;
+    sourceChannel: ChannelId;
+  }): InviteShareLink;
+
+  /**
+   * Extract a channel-specific invite token from an inbound message
+   * (e.g. Telegram `/start iv_<token>`). Optional — only needed for
+   * channels with link-based invites.
+   */
+  extractInboundToken?(params: {
+    commandIntent?: Record<string, unknown>;
+    content: string;
+    sourceMetadata?: Record<string, unknown>;
+  }): string | undefined;
+
+  /**
+   * Resolve the channel-specific handle to reach the assistant (e.g.
+   * // generic-examples:ignore-next-line — reason: illustrative docstring examples, not real data
+   * "@botName", "+15551234567", "hello@vellum.me").
+   * Returns `undefined` when the handle cannot be resolved (e.g.
+   * credentials not yet configured).
+   */
+  resolveChannelHandle?(): string | undefined;
+
+  /**
+   * Async variant of `resolveChannelHandle` for adapters that need to
+   * perform I/O (e.g. querying a provider API for the assigned address).
+   * When both are present, `resolveAdapterHandle()` prefers this method.
+   */
+  resolveChannelHandleAsync?(): Promise<string | undefined>;
+}