@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/runtime/channel-readiness-service.ts

@@ -1,13 +1,10 @@
 import { isInviteCodeRedemptionEnabled } from "@vellumai/gateway-client";
-import {
-  normalizePublicBaseUrl,
-  resolveTwilioPublicBaseUrl,
-} from "@vellumai/service-contracts/twilio-ingress";
+import { z } from "zod";
 
 import { resolveTwilioPhoneNumber } from "../calls/twilio-config.js";
 import { hasTwilioCredentials } from "../calls/twilio-rest.js";
-import { getIsPlatform } from "../config/env-registry.js";
 import { getNestedValue, loadRawConfig } from "../config/loader.js";
+import { hasWebhookRoutingConfigured } from "../config/webhook-routing.js";
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
 import { resolveWhatsAppDisplayNumber } from "./channel-invite-transports/whatsapp.js";
@@ -23,39 +20,95 @@ import type {
 /** Remote check results are cached for 5 minutes before being considered stale. */
 export const REMOTE_TTL_MS = 5 * 60 * 1000;
 
-function hasIngressConfigured(options: { twilio?: boolean } = {}): boolean {
-  try {
-    const raw = loadRawConfig();
-    const ingress = (raw?.ingress ?? {}) as Record<string, unknown>;
-    const effectiveBaseUrl = options.twilio
-      ? (resolveTwilioPublicBaseUrl(ingress) ?? "")
-      : (normalizePublicBaseUrl(ingress.publicBaseUrl) ?? "");
-    const enabled =
-      (ingress.enabled as boolean | undefined) ??
-      (effectiveBaseUrl ? true : false);
-    return enabled && effectiveBaseUrl.trim().length > 0;
-  } catch {
-    return false;
+/**
+ * Bot scopes the Slack manifest requests that the app cannot work without.
+ *
+ * Slack's install flow can return a token carrying a fraction of the manifest's
+ * scopes while `auth.test` still succeeds — a live install produced 2 of 18, and
+ * the first real API call failed with `missing_scope`. `auth.test` passing is
+ * therefore not evidence the install is usable; the granted set has to be read
+ * off the `x-oauth-scopes` response header and compared.
+ *
+ * Mirrors the non-optional half of `oauth_config.scopes.bot` in
+ * `skills/slack-app-setup/scripts/build-manifest.ts` (and its copy in
+ * `clients/web/src/utils/slack-manifest.ts`). Scopes the manifest marks
+ * declinable are deliberately absent: a workspace may refuse those at the
+ * consent screen, and flagging that choice as a fault would be noise.
+ */
+const SLACK_REQUIRED_BOT_SCOPES = [
+  "app_mentions:read",
+  "assistant:write",
+  "channels:history",
+  "channels:read",
+  "chat:write",
+  "groups:history",
+  "groups:read",
+  "im:history",
+  "im:read",
+  "im:write",
+  "mpim:history",
+  "mpim:read",
+  "users:read",
+] as const;
+
+/**
+ * Shape of a Slack `auth.test` response.
+ *
+ * Validated rather than cast: this crosses a runtime boundary, so a `ok` that
+ * arrives as a string would slip past a cast and make `!data.ok` decide on the
+ * wrong value. Unknown keys are ignored — Slack adds fields over time and a
+ * new one is not a reason to report the integration broken.
+ */
+const AuthTestResponseSchema = z.object({
+  ok: z.boolean(),
+  error: z.string().optional(),
+  team_id: z.string().optional(),
+  team: z.string().optional(),
+  user: z.string().optional(),
+});
+
+/** Slack returns `x-oauth-scopes` as a comma-separated list on every response. */
+function parseGrantedScopes(raw: string | null): string[] | null {
+  if (raw === null) {
+    return null;
   }
+  const scopes = raw
+    .split(",")
+    .map((scope) => scope.trim())
+    .filter(Boolean);
+  return scopes.length > 0 ? scopes : null;
 }
 
-function hasWebhookRoutingConfigured(
-  allowManagedCallbacks = false,
-  options: { twilio?: boolean } = {},
-): {
-  configured: boolean;
-  usesManagedCallbacks: boolean;
-} {
-  const ingressConfigured = hasIngressConfigured(options);
-  if (ingressConfigured) {
-    return { configured: true, usesManagedCallbacks: false };
+/**
+ * Compare what Slack granted against what the app needs.
+ *
+ * Passes when the header is unreadable: a check that cannot see the grant must
+ * not report a fault it has no evidence for. Reinstalling re-grants the scopes
+ * to the same token, so recovery needs no new credentials — but Slack forces an
+ * app "update" prompt first, and skipping it leaves the scopes unchanged.
+ */
+function scopeGrantCheck(rawHeader: string | null): ReadinessCheckResult {
+  const granted = parseGrantedScopes(rawHeader);
+  if (granted === null) {
+    return check(
+      "scopes_granted",
+      true,
+      "Slack did not report granted scopes — skipped",
+      "Slack did not report granted scopes — skipped",
+    );
   }
 
-  const usesManagedCallbacks = allowManagedCallbacks && getIsPlatform();
-  return {
-    configured: usesManagedCallbacks,
-    usesManagedCallbacks,
-  };
+  const grantedSet = new Set(granted);
+  const missing = SLACK_REQUIRED_BOT_SCOPES.filter(
+    (scope) => !grantedSet.has(scope),
+  );
+
+  return check(
+    "scopes_granted",
+    missing.length === 0,
+    `Bot token carries all ${SLACK_REQUIRED_BOT_SCOPES.length} required scopes`,
+    `Bot token is missing ${missing.length} of ${SLACK_REQUIRED_BOT_SCOPES.length} required scopes (${missing.join(", ")}) — open the app at https://api.slack.com/apps, accept the update prompt, then OAuth & Permissions → Reinstall to Workspace`,
+  );
 }
 
 // ── Shared check helpers ────────────────────────────────────────────────────
@@ -298,13 +351,18 @@ const slackProbe: ChannelProbe = {
         method: "POST",
         headers: { Authorization: `Bearer ${botToken}` },
       });
-      const data = (await res.json()) as {
-        ok: boolean;
-        error?: string;
-        team_id?: string;
-        team?: string;
-        user?: string;
-      };
+      const parsed = AuthTestResponseSchema.safeParse(await res.json());
+      if (!parsed.success) {
+        return [
+          check(
+            "auth_test",
+            false,
+            "Slack auth.test ok",
+            `Slack auth.test returned an unexpected response shape: ${parsed.error.issues.map((i) => i.path.join(".") || "(root)").join(", ")}`,
+          ),
+        ];
+      }
+      const data = parsed.data;
       if (!data.ok) {
         return [
           check(
@@ -334,6 +392,7 @@ const slackProbe: ChannelProbe = {
           "Stored workspace matches bot token",
           `Stored workspace ${storedTeamId} does not match bot token's workspace ${data.team_id ?? "unknown"} — run 'assistant channels slack reconnect' to refresh metadata`,
         ),
+        scopeGrantCheck(res.headers.get("x-oauth-scopes")),
       ];
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);

package/src/runtime/channel-retry-sweep.ts

@@ -2,6 +2,7 @@
  * Periodic retry sweep for failed channel inbound events.
  */
 
+import type { AssistantEvent } from "../api/index.js";
 import {
   type ChannelId,
   isChannelId,
@@ -12,7 +13,6 @@ import { isConversationBusyError } from "../daemon/conversation-messaging.js";
 import { findConversation } from "../daemon/conversation-registry.js";
 import { getDiskPressureStatus } from "../daemon/disk-pressure-guard.js";
 import { classifyDiskPressureTurnPolicy } from "../daemon/disk-pressure-policy.js";
-import type { ServerMessage } from "../daemon/message-protocol.js";
 import type { TrustContext } from "../daemon/trust-context-types.js";
 import { updateDeliveredSegmentCount } from "../persistence/delivery-channels.js";
 import {
@@ -156,12 +156,22 @@ function parseStoredSlackInbound(
 }
 
 /**
- * Fallback for payloads stored before {@link parseStoredSlackInbound}'s capture
- * existed: reconstruct the minimal `{ channelId, channelTs }` from fields the
- * payload has always carried, so those in-flight events still dedup on replay.
- * `channelTs` mirrors the live `sourceMessageId ?? externalMessageId` derivation.
- * slackMeta is partial here (only the key-bearing fields), which is acceptable
- * for the short drain window of pre-upgrade retries.
+ * Fallback when the payload carries no captured `slackInbound`: reconstruct
+ * what we can from the fields the payload has always carried, so the event
+ * still dedups on replay. `channelTs` mirrors the live
+ * `sourceMessageId ?? externalMessageId` derivation.
+ *
+ * Two kinds of event land here, not just one. Payloads stored before the
+ * capture existed are the obvious case and drain quickly. The durable case is
+ * a crash between `storePayload` (which runs at the top of the handler) and
+ * `storeInboundSlackMetadata` (which runs on dispatch, after the awaited Slack
+ * backfills) — `recoverOrphanedChannelEvents` promotes that orphan onto the
+ * sweep and it arrives here with a full `sourceMetadata` but no `slackInbound`.
+ *
+ * So anything the live path reads off `sourceMetadata` and renders into the
+ * turn has to be recovered here too, or crash recovery replays an impoverished
+ * turn. slackMeta is still partial (the rest is presentation, reconstructible
+ * from the row), but the turn-shaping fields are not optional.
  */
 function buildReplaySlackInbound(params: {
   sourceChannel: ChannelId;
@@ -179,7 +189,14 @@ function buildReplaySlackInbound(params: {
   if (!channelTs) {
     return undefined;
   }
-  return { channelId: params.externalChatId, channelTs };
+  const appContext = params.sourceMetadata?.appContext;
+  return {
+    channelId: params.externalChatId,
+    channelTs,
+    ...(Array.isArray(appContext?.entities) && appContext.entities.length > 0
+      ? { appContext }
+      : {}),
+  };
 }
 
 /**
@@ -368,7 +385,7 @@ export async function sweepFailedEvents(
         ? payload.slackStreamMessageTs
         : undefined;
     let replyMessageId: string | undefined;
-    const observeAgentEvent = (msg: ServerMessage): void => {
+    const observeAgentEvent = (msg: AssistantEvent): void => {
       if (
         msg.type === "message_complete" &&
         (msg.source === undefined || msg.source === "main") &&
@@ -401,12 +418,6 @@ export async function sweepFailedEvents(
     // `slackInbound` when present (identical idempotency key + full slackMeta),
     // else the reconstructed fallback — so a replay of an already-persisted turn
     // dedups instead of running a second agent loop.
-    const prepared = prepareChannelInboundContent({
-      trimmedContent: content,
-      trustClass: trustContext.trustClass,
-      sourceChannel,
-      requesterIdentifier: trustContext.requesterIdentifier,
-    });
     const replaySlackInbound =
       parseStoredSlackInbound(payload.slackInbound) ??
       buildReplaySlackInbound({
@@ -415,6 +426,18 @@ export async function sweepFailedEvents(
         sourceMetadata,
         externalMessageId,
       });
+    // The captured `slackInbound` carries the sender's Slack `app_context`, so
+    // the replayed turn is prepared with the same context block the live turn
+    // rendered. Payloads predating the capture simply have none.
+    const prepared = prepareChannelInboundContent({
+      trimmedContent: content,
+      trustClass: trustContext.trustClass,
+      sourceChannel,
+      requesterIdentifier: trustContext.requesterIdentifier,
+      ...(replaySlackInbound?.appContext
+        ? { slackAppContext: replaySlackInbound.appContext }
+        : {}),
+    });
 
     // Shared replay options. The idempotency-bearing `slackInbound` is added
     // only on the first attempt; the incomplete-turn re-run below omits it so it

package/src/runtime/confirmation-request-guardian-bridge.ts

@@ -19,6 +19,7 @@ import {
   recordApprovalCardDelivery,
   recordGuardianRequestDeliveries,
 } from "../notifications/guardian-delivery-recorder.js";
+import { buildVellumCardAffinity } from "../notifications/vellum-card-affinity.js";
 import { canonicalizeInboundIdentity } from "../util/canonicalize-identity.js";
 import { getLogger } from "../util/logger.js";
 import { resolveApprovalSourceReference } from "./approval-source-link.js";
@@ -166,6 +167,9 @@ export async function bridgeConfirmationRequestToGuardian(
     sourceChannel,
     sourceContextId: conversationId,
     requiresConversation: true,
+    // Pin the in-app (vellum) card to the conversation the confirmation was
+    // emitted in, so the guardian decides it in context.
+    ...(buildVellumCardAffinity(conversationId) ?? {}),
     attentionHints: {
       requiresAction: true,
       urgency: "high",

package/src/runtime/guardian-reply-router.ts

@@ -46,6 +46,8 @@ import {
   buildGuardianDisambiguationExample,
   buildGuardianDisambiguationLabel,
   buildGuardianInvalidActionReply,
+  parseQuestionAnswerActionId,
+  QUESTION_SKIP_ACTION_ID,
   resolveGuardianInstructionModeForRequest,
 } from "../notifications/guardian-question-mode.js";
 import { getLogger } from "../util/logger.js";
@@ -58,6 +60,7 @@ import type {
   ApprovalConversationContext,
   ApprovalConversationGenerator,
 } from "./http-types.js";
+import * as pendingInteractions from "./pending-interactions.js";
 import { parseReactionCallbackData } from "./routes/channel-route-shared.js";
 
 const log = getLogger("guardian-reply-router");
@@ -181,6 +184,38 @@ function parseCallbackAction(data: string): ParsedCallback | null {
   return { requestId, action };
 }
 
+/**
+ * Parse an `apr:<requestId>:<token>` callback whose token is an answer-option
+ * selection rather than an approval action. Same wire prefix as approval
+ * buttons — question cards are ordinary guardian-request cards — but the
+ * token is validated against the answer scheme by the caller, which also
+ * confirms the target request is answer-mode before applying anything.
+ */
+function parseAnswerCallback(
+  data: string,
+): { requestId: string; token: string } | null {
+  const parts = data.split(":");
+  if (parts.length !== 3 || parts[0] !== "apr") {
+    return null;
+  }
+  const [, requestId, token] = parts;
+  if (!requestId || !token) {
+    return null;
+  }
+  return { requestId, token };
+}
+
+/**
+ * Whether the parked `question` interaction behind an ask_question guardian
+ * request is still live. An answer path must not commit a decision against a
+ * request whose interaction is gone (answered on another surface, timed out,
+ * superseded) — there is nothing left to resolve, and the message/tap should
+ * take the stale path instead.
+ */
+function hasLiveQuestionInteraction(requestId: string): boolean {
+  return pendingInteractions.get(requestId)?.kind === "question";
+}
+
 // ---------------------------------------------------------------------------
 // Request code parser
 // ---------------------------------------------------------------------------
@@ -392,6 +427,40 @@ export async function routeGuardianReply(
         emissionContext,
       );
     }
+
+    // Answer-option tap on a question card: the action token is an answer
+    // selection (`answer_<idx>` / `answer_skip`), not an approval action, so
+    // `parseCallbackAction` rejects it above. Accept it only when the target
+    // request actually resolves to answer mode — an answer token aimed at an
+    // approval-mode request is never treated as a decision — and the parked
+    // interaction is still live, so a tap on a stale card (answered elsewhere,
+    // timed out) falls through to the stale-callback handling instead of
+    // committing a decision that can no longer resolve anything. The token
+    // rides as `userText`; the question resolver maps it to the selected
+    // option.
+    const answerTap = parseAnswerCallback(callbackData);
+    if (answerTap) {
+      const request = await getGuardianRequestOrNull(answerTap.requestId);
+      if (
+        request &&
+        resolveRequestInstructionMode(request) === "answer" &&
+        parseQuestionAnswerActionId(answerTap.token) &&
+        !request.callSessionId &&
+        hasLiveQuestionInteraction(request.id)
+      ) {
+        return applyDecision(
+          request.id,
+          answerTap.token === QUESTION_SKIP_ACTION_ID
+            ? "reject"
+            : "approve_once",
+          actor,
+          answerTap.token,
+          channelDeliveryContext,
+          emissionContext,
+        );
+      }
+      return notConsumed();
+    }
   }
 
   // ── 2. Request code parsing (6-char alphanumeric prefix) ──
@@ -544,6 +613,45 @@ export async function routeGuardianReply(
     }
   }
 
+  // ── 2.55. Bare-text answer to a single pending question ──
+  // When exactly one pending request is answer-mode (an ask_question), an
+  // unprefixed guardian reply IS the answer — "3pm works" must not require a
+  // request code, fall into approve/reject inference, or leak through to a
+  // normal agent turn (which would defer behind the parked question's
+  // processing lock and hang until the prompt timeout). Multiple pending
+  // requests keep the disambiguation flow below, which already prints
+  // per-mode reply examples.
+  //
+  // Deliberately narrow — this branch consumes ordinary prose, so it only
+  // fires when the message is unambiguously the answer:
+  //  - same conversation the question was asked in (`sourceConversationId`)
+  //    — under the identity-fallback scope a guardian's pending requests are
+  //    visible cross-chat, and prose typed in an unrelated chat must never
+  //    resolve a question elsewhere. Explicit codes/callbacks stay cross-chat.
+  //  - the parked interaction is still live — after an app-card answer or a
+  //    prompt timeout the request row can briefly outlive the interaction,
+  //    and matching it would swallow the message into a decision that can no
+  //    longer resolve anything. (Voice questions carry no such interaction
+  //    and keep their existing code/NL answer paths.)
+  if (messageText.length > 0 && pendingRequests.length === 1) {
+    const soleRequest = pendingRequests[0];
+    if (
+      resolveRequestInstructionMode(soleRequest) === "answer" &&
+      !soleRequest.callSessionId &&
+      soleRequest.sourceConversationId === conversationId &&
+      hasLiveQuestionInteraction(soleRequest.id)
+    ) {
+      return applyDecision(
+        soleRequest.id,
+        "approve_once",
+        actor,
+        messageText,
+        channelDeliveryContext,
+        emissionContext,
+      );
+    }
+  }
+
   // ── 2.6. Deterministic plain-text decisions for known pending targets ──
   // Desktop sessions intentionally do not enable NL classification; when the
   // caller has exactly one known pending request and sends an explicit

package/src/runtime/http-server.ts

@@ -37,6 +37,10 @@ import {
   activeSttStreamSessions,
   SttStreamSession,
 } from "../stt/stt-stream-session.js";
+import {
+  startTelegramWebhookHealthSweep,
+  stopTelegramWebhookHealthSweep,
+} from "../telegram/webhook-health.js";
 import { getLogger } from "../util/logger.js";
 import { authenticateRequest } from "./auth/middleware.js";
 import { parseSub } from "./auth/subject.js";
@@ -504,11 +508,15 @@ export class RuntimeHttpServer {
 
     startInferenceProfileSessionReaper();
     log.info("Inference profile session reaper started");
+
+    startTelegramWebhookHealthSweep();
+    log.info("Telegram webhook health sweep started");
   }
 
   async stop(): Promise<void> {
     stopGuardianExpirySweep();
     stopInferenceProfileSessionReaper();
+    stopTelegramWebhookHealthSweep();
     if (this.retrySweepTimer) {
       clearInterval(this.retrySweepTimer);
       this.retrySweepTimer = null;

package/src/runtime/http-types.ts

@@ -16,7 +16,7 @@ import type {
 // Re-export so route modules (background-dispatch, etc.) can pull the type
 // from the runtime barrel without reaching into daemon internals.
 export type { SlackInboundMessageMetadata };
-import type { ServerMessage } from "../daemon/message-protocol.js";
+import type { AssistantEvent } from "../api/index.js";
 import type { AssistantEventHub } from "./assistant-event-hub.js";
 
 export type {
@@ -84,7 +84,7 @@ export interface RuntimeMessageConversationOptions {
    */
   displayContent?: string;
   /** Optional callback to receive real-time agent loop events (text deltas, tool starts, etc.). */
-  onEvent?: (msg: ServerMessage) => void;
+  onEvent?: (msg: AssistantEvent) => void;
   /**
    * Optional LLM call-site identifier. Channel ingress and other inbound paths
    * may pass this so the daemon's per-call provider config picks up the right

package/src/runtime/process-role.ts

@@ -0,0 +1,42 @@
+/**
+ * Process-role signal: whether this OS process is the main assistant daemon or
+ * something else (a sidecar worker — the resource monitor, memory jobs worker,
+ * schedule worker, route host — the CLI, a test, …).
+ *
+ * The daemon owns the singletons real clients connect to — the event hub and
+ * its SSE fan-out chief among them. Any other process runs its own disjoint
+ * copies, so anything it publishes locally reaches no client; such code routes
+ * to the live daemon over IPC when {@link isMainDaemonProcess} is false.
+ *
+ * Only the daemon knows it is the daemon: its entrypoint calls
+ * {@link markCurrentProcessAsMainDaemon} once at startup. Every other process
+ * (which never runs that entrypoint) is a non-daemon by default — no per-worker
+ * bookkeeping to keep in sync.
+ *
+ * State lives on the shared `globalThis.vellumAssistant.mainDaemonProcess` slot
+ * (like the other process-scoped singletons, and typed once by the ambient
+ * `VellumAssistantNamespace` in `src/vellum-assistant-namespace.d.ts`) so the
+ * test preload can default a test process to "main daemon" — a test runs daemon
+ * code in-process and expects local hub delivery — without importing this
+ * module.
+ */
+
+function ns(): VellumAssistantNamespace {
+  return (globalThis.vellumAssistant ??= {});
+}
+
+/**
+ * Mark the current process as the main assistant daemon. Called once, early in
+ * the daemon entrypoint (`runDaemon`), before anything can publish an event.
+ */
+export function markCurrentProcessAsMainDaemon(): void {
+  ns().mainDaemonProcess = true;
+}
+
+/**
+ * Whether this is the main assistant daemon process. False everywhere the
+ * daemon entrypoint did not run — sidecar workers, the route host, the CLI.
+ */
+export function isMainDaemonProcess(): boolean {
+  return ns().mainDaemonProcess === true;
+}