@vellumai/assistant 0.10.12 → 0.11.0-staging.1

package/src/runtime/routes/inbound-stages/inbound-content-prep.ts

@@ -6,7 +6,9 @@
  * before it enters model context — the model is instructed never to follow
  * instructions found inside those boundaries. Guardian messages are trusted and
  * pass through unwrapped. Slack additionally keeps the raw text as
- * `displayContent` so the UI shows the message the sender actually typed.
+ * `displayContent` so the UI shows the message the sender actually typed, and
+ * prepends a `<slack_app_context>` block when the event reported what the
+ * sender had open in Slack.
  *
  * Shared by the live ingress path (`inbound-message-handler.ts`) and the retry
  * sweep (`channel-retry-sweep.ts`) so both prepare content identically: a turn
@@ -14,9 +16,114 @@
  * boundary cannot be skipped on a retry or crash-recovery path.
  */
 import type { ChannelId } from "../../../channels/types.js";
+import type {
+  SlackAppContext,
+  SlackAppContextEntity,
+} from "../../../daemon/handlers/shared.js";
 import type { TrustContext } from "../../../daemon/trust-context-types.js";
 import { wrapUntrustedContent } from "../../../security/untrusted-content.js";
 
+/** Slack `app_context` entity types whose `value` is a plain object id. */
+const SLACK_APP_CONTEXT_ID_LABELS = new Map<string, string>([
+  ["slack#/types/channel_id", "channel"],
+  ["slack#/types/canvas_id", "canvas"],
+  ["slack#/types/list_id", "list"],
+]);
+
+/** The one entity type whose `value` is an object rather than an id string. */
+const SLACK_APP_CONTEXT_MESSAGE_TYPE = "slack#/types/message_context";
+
+/**
+ * Shape of a Slack-issued object id (channel `C…`/`G…`/`D…`, canvas/list `F…`).
+ * The rendered block sits OUTSIDE the `<external_content>` fence, so every
+ * value that reaches it must be provably Slack-minted rather than sender-typed
+ * text — an entity whose id does not match this is dropped, not rendered.
+ */
+const SLACK_OBJECT_ID_PATTERN = /^[A-Z][A-Z0-9]{1,31}$/;
+
+/** Slack message `ts`, `<seconds>.<micros>`. Same rationale as the id pattern. */
+const SLACK_TS_PATTERN = /^\d{1,19}\.\d{1,19}$/;
+
+/**
+ * Cap on rendered entities. Slack sends a handful; the cap bounds how much
+ * trusted framing a malformed payload can occupy.
+ */
+const MAX_APP_CONTEXT_ENTITIES = 8;
+
+/**
+ * Render the sender's active Slack context as a `<slack_app_context>` block, or
+ * `undefined` when no entity survives validation.
+ *
+ * The block is deliberately NOT fenced as untrusted content. Every value it
+ * carries is a Slack-issued opaque identifier, validated against the patterns
+ * above, so there is no sender-authored text in it — and the model has to be
+ * able to act on the block (resolving "this channel", "that message") rather
+ * than treat it as inert data it must ignore. Nothing derived from a channel
+ * name, canvas title, or any other user-writable string may be added here
+ * without moving the block inside the fence.
+ *
+ * The block reaches the model for this turn only: persistence stores
+ * `displayContent` (the raw text), so replayed history carries the message
+ * without it. That is the intended lifetime — `app_context` describes what the
+ * sender had open when they sent the message, not what they have open now.
+ */
+function renderSlackAppContext(
+  entities: readonly SlackAppContextEntity[],
+): string | undefined {
+  const lines: string[] = [];
+
+  for (const entity of entities) {
+    if (lines.length >= MAX_APP_CONTEXT_ENTITIES) {
+      break;
+    }
+    // Entities arrive unvalidated on both paths (an unparsed HTTP body live, a
+    // stored payload on replay), so a malformed element is skipped, not thrown on.
+    if (!entity || typeof entity !== "object") {
+      continue;
+    }
+    const idLabel = SLACK_APP_CONTEXT_ID_LABELS.get(entity.type);
+    if (idLabel) {
+      if (
+        typeof entity.value === "string" &&
+        SLACK_OBJECT_ID_PATTERN.test(entity.value)
+      ) {
+        lines.push(`${idLabel}: ${entity.value}`);
+      }
+      continue;
+    }
+    if (
+      entity.type !== SLACK_APP_CONTEXT_MESSAGE_TYPE ||
+      !entity.value ||
+      typeof entity.value !== "object"
+    ) {
+      continue;
+    }
+    const { channelId, messageTs } = entity.value;
+    if (
+      channelId &&
+      messageTs &&
+      SLACK_OBJECT_ID_PATTERN.test(channelId) &&
+      SLACK_TS_PATTERN.test(messageTs)
+    ) {
+      lines.push(`message: channel ${channelId} ts ${messageTs}`);
+    }
+  }
+
+  if (lines.length === 0) {
+    return undefined;
+  }
+
+  return [
+    "<slack_app_context>",
+    "Slack reports these as open for the sender right now. Use the ids to",
+    'resolve references like "this channel" or "that message"; when the',
+    "reference is still ambiguous, ask rather than guess.",
+    "",
+    ...lines,
+    "</slack_app_context>",
+  ].join("\n");
+}
+
 export interface PreparedChannelInboundContent {
   /**
    * Model-facing content. For non-guardian senders this is `trimmedContent`
@@ -27,8 +134,10 @@ export interface PreparedChannelInboundContent {
   /**
    * User-facing display copy (the raw, unwrapped text) persisted alongside the
    * model content so the UI renders what the sender typed rather than the
-   * boundary-wrapped form. Set only for non-guardian Slack turns, matching the
-   * live ingress path; absent otherwise (persistence falls back to `content`).
+   * boundary-wrapped form. Set on any Slack turn whose `content` diverges from
+   * the raw text — non-guardian turns (which are fenced) and turns carrying a
+   * `<slack_app_context>` block. Absent otherwise (persistence falls back to
+   * `content`).
    */
   displayContent?: string;
 }
@@ -43,21 +152,44 @@ export function prepareChannelInboundContent(params: {
   trustClass: TrustContext["trustClass"];
   sourceChannel: ChannelId;
   requesterIdentifier?: string;
+  /**
+   * The sender's active Slack context, when the inbound event carried one.
+   * Ignored for non-Slack channels.
+   */
+  slackAppContext?: SlackAppContext;
 }): PreparedChannelInboundContent {
-  const { trimmedContent, trustClass, sourceChannel, requesterIdentifier } =
-    params;
+  const {
+    trimmedContent,
+    trustClass,
+    sourceChannel,
+    requesterIdentifier,
+    slackAppContext,
+  } = params;
 
   const isGuardian = trustClass === "guardian";
-  const content = isGuardian
+  const messageContent = isGuardian
     ? trimmedContent
     : wrapUntrustedContent(trimmedContent, {
         source: sourceChannel === "slack" ? "slack" : "webhook",
         sourceDetail: requesterIdentifier,
       });
 
-  // Slack persists the raw text as display copy for non-guardian turns so the
-  // transcript shows the sender's words, not the wrapped form.
-  if (!isGuardian && sourceChannel === "slack") {
+  // Prepended outside the fence — see `renderSlackAppContext` for why that is
+  // safe and what would make it unsafe.
+  // `Array.isArray` rather than a truthiness check: on the replay path this
+  // object comes straight off the stored payload without re-validation.
+  const appContextBlock =
+    sourceChannel === "slack" && Array.isArray(slackAppContext?.entities)
+      ? renderSlackAppContext(slackAppContext.entities)
+      : undefined;
+  const content = appContextBlock
+    ? `${appContextBlock}\n\n${messageContent}`
+    : messageContent;
+
+  // Slack persists the raw text as display copy whenever the model content
+  // diverges from it, so the transcript shows the sender's words rather than
+  // the wrapped form or the prepended context block.
+  if (sourceChannel === "slack" && (!isGuardian || appContextBlock)) {
     return { content, displayContent: trimmedContent };
   }
   return { content };

package/src/runtime/routes/index.ts

@@ -101,6 +101,7 @@ import { ROUTES as VERCEL_ROUTES } from "./integrations/vercel.js";
 import { ROUTES as INTERNAL_OAUTH_ROUTES } from "./internal-oauth-routes.js";
 import { ROUTES as INTERNAL_TELEMETRY_ROUTES } from "./internal-telemetry-routes.js";
 import { ROUTES as INTERNAL_TWILIO_ROUTES } from "./internal-twilio-routes.js";
+import { ROUTES as LIFECYCLE_ROUTES } from "./lifecycle-routes.js";
 import { ROUTES as LIVE_VOICE_ROUTES } from "./live-voice-routes.js";
 import { ROUTES as LLM_CALL_SITES_ROUTES } from "./llm-call-sites-routes.js";
 import { ROUTES as LOG_EXPORT_ROUTES } from "./log-export-routes.js";
@@ -241,6 +242,7 @@ export const ROUTES: RouteDefinition[] = [
   ...MCP_AUTH_ROUTES,
   ...OAUTH_CONNECT_ROUTES,
   ...INTERNAL_TWILIO_ROUTES,
+  ...LIFECYCLE_ROUTES,
   ...LIVE_VOICE_ROUTES,
   ...LOG_EXPORT_ROUTES,
   ...LLM_CALL_SITES_ROUTES,

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

@@ -0,0 +1,199 @@
+/**
+ * Lifecycle drain endpoints backing `vellum sleep --wait`.
+ *
+ * The quiesce lease pauses the STARTING of new background LLM work (heartbeat
+ * beats, schedule/watcher/sequence claims, memory-job claims) across the
+ * daemon and its worker processes; drain-status reports what is still in
+ * flight so a client can wait for the assistant to go idle before stopping
+ * it. Enqueue paths stay open — work queued during a drain runs after the
+ * next start. The lease is TTL-bound and refreshed by the waiting client, so
+ * an abandoned drain can never leave background work paused.
+ */
+
+import { z } from "zod";
+
+import { listRunningHeartbeatRuns } from "../../heartbeat/heartbeat-run-store.js";
+import { listProcessingConversations } from "../../persistence/conversation-crud.js";
+import { listRunningMemoryJobs } from "../../persistence/jobs-store.js";
+import {
+  clearLifecycleQuiesce,
+  DEFAULT_QUIESCE_TTL_MS,
+  getLifecycleQuiesceUntil,
+  setLifecycleQuiesce,
+} from "../../persistence/lifecycle-quiesce.js";
+import { listRunningScheduleRuns } from "../../schedule/schedule-store.js";
+import { getLogger } from "../../util/logger.js";
+import { listRuns as listWorkflowRuns } from "../../workflows/journal-store.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import { BadRequestError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+const log = getLogger("lifecycle-routes");
+
+const quiesceResponseSchema = z.object({
+  quiescedUntil: z
+    .number()
+    .describe("Epoch ms when the quiesce lease expires."),
+});
+
+const activeConversationSchema = z.object({
+  conversationId: z.string(),
+  title: z.string().nullable(),
+  originChannel: z.string().nullable(),
+  originInterface: z.string().nullable(),
+  processingStartedAt: z.number(),
+});
+
+const runningMemoryJobSchema = z.object({
+  id: z.string(),
+  type: z.string(),
+  startedAt: z.number().nullable(),
+});
+
+const runningScheduleRunSchema = z.object({
+  runId: z.string(),
+  scheduleName: z.string().nullable(),
+  startedAt: z.number(),
+});
+
+const runningWorkflowRunSchema = z.object({
+  runId: z.string(),
+  name: z.string().nullable(),
+  startedAt: z.number().nullable(),
+});
+
+const runningHeartbeatRunSchema = z.object({
+  runId: z.string(),
+  startedAt: z.number(),
+});
+
+const drainStatusResponseSchema = z.object({
+  quiescedUntil: z.number().nullable(),
+  idle: z
+    .boolean()
+    .describe(
+      "True when no conversation turn, memory job, schedule run, workflow run, or heartbeat run is in flight.",
+    ),
+  activeConversations: z.array(activeConversationSchema),
+  memoryJobs: z.array(runningMemoryJobSchema),
+  scheduleRuns: z.array(runningScheduleRunSchema),
+  workflowRuns: z.array(runningWorkflowRunSchema),
+  heartbeatRuns: z.array(runningHeartbeatRunSchema),
+});
+
+/**
+ * Age cap for `running` heartbeat rows in the drain snapshot. A beat orphaned
+ * by a crash keeps its `running` status until a later boot's stale sweep, so
+ * an unbounded read would let a phantom row hold the drain open indefinitely.
+ * Real beats finish well inside this bound (the runner enforces its own
+ * timeout).
+ */
+const HEARTBEAT_RUN_MAX_AGE_MS = 15 * 60_000;
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "quiesceLifecycle",
+    endpoint: "lifecycle/quiesce",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Arm or refresh the drain quiesce lease",
+    description:
+      "Pauses the starting of new background work (heartbeat, schedules, watchers, sequences, memory jobs) for the lease TTL. Refresh by calling again; the lease self-expires so an abandoned drain never leaves background work paused.",
+    tags: ["system"],
+    requestBody: z.object({
+      ttlMs: z
+        .number()
+        .optional()
+        .describe("Lease TTL in ms (clamped to a sane range)."),
+    }),
+    responseBody: quiesceResponseSchema,
+    handler: (args: RouteHandlerArgs) => {
+      const raw = args.body?.ttlMs;
+      let ttlMs = DEFAULT_QUIESCE_TTL_MS;
+      if (raw !== undefined) {
+        if (typeof raw !== "number" || !Number.isFinite(raw)) {
+          throw new BadRequestError("ttlMs must be a finite number");
+        }
+        ttlMs = raw;
+      }
+      const quiescedUntil = setLifecycleQuiesce(ttlMs);
+      log.info({ quiescedUntil }, "Lifecycle quiesce lease armed");
+      return { quiescedUntil };
+    },
+  },
+  {
+    operationId: "releaseLifecycleQuiesce",
+    endpoint: "lifecycle/quiesce",
+    method: "DELETE",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Release the drain quiesce lease",
+    description:
+      "Resumes background work immediately instead of waiting for the lease TTL to expire (e.g. when a drain is cancelled).",
+    tags: ["system"],
+    responseBody: z.object({ released: z.boolean() }),
+    handler: () => {
+      clearLifecycleQuiesce();
+      log.info("Lifecycle quiesce lease released");
+      return { released: true };
+    },
+  },
+  {
+    operationId: "getLifecycleDrainStatus",
+    endpoint: "lifecycle/drain-status",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "In-flight background work",
+    description:
+      "Reports conversation turns, memory jobs, schedule runs, workflow runs, and heartbeat runs currently in flight, plus the active quiesce lease. `idle: true` means it is safe to stop the assistant without interrupting work.",
+    tags: ["system"],
+    responseBody: drainStatusResponseSchema,
+    handler: () => {
+      // Every read THROWS on failure (surfacing as a 5xx the client retries):
+      // for a drain decision, a failed read must not pass for proof of
+      // absence, or the client stops the assistant over unobservable
+      // in-flight work. Only the quiesce GATES are fail-open — this snapshot
+      // fails closed.
+      const activeConversations = listProcessingConversations();
+      const memoryJobs = listRunningMemoryJobs();
+      const scheduleRuns = listRunningScheduleRuns();
+      // Workflows launched by a schedule outlive their schedule run — the
+      // scheduler fires them and completes its own run row immediately — so
+      // a running workflow must hold the drain open in its own right.
+      const workflowRuns = listWorkflowRuns({
+        limit: 20,
+        status: "running",
+      }).map((run) => ({
+        runId: run.id,
+        name: run.name,
+        startedAt: run.createdAt,
+      }));
+      // A beat between startHeartbeatRun() and its background conversation
+      // existing (e.g. mid credential-health check) has a running row but no
+      // processing conversation yet.
+      const heartbeatRuns = listRunningHeartbeatRuns(HEARTBEAT_RUN_MAX_AGE_MS);
+      return {
+        quiescedUntil: getLifecycleQuiesceUntil(),
+        idle:
+          activeConversations.length === 0 &&
+          memoryJobs.length === 0 &&
+          scheduleRuns.length === 0 &&
+          workflowRuns.length === 0 &&
+          heartbeatRuns.length === 0,
+        activeConversations,
+        memoryJobs,
+        scheduleRuns,
+        workflowRuns,
+        heartbeatRuns,
+      };
+    },
+  },
+];

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

@@ -30,8 +30,7 @@ import {
   getSecureKeyAsync,
 } from "../../security/secure-keys.js";
 import { getExistingDeviceId } from "../../util/device-id.js";
-import { buildAssistantEvent } from "../assistant-event.js";
-import { assistantEventHub } from "../assistant-event-hub.js";
+import { broadcastMessage } from "../assistant-event-hub.js";
 import { ACTOR_PRINCIPALS, LOCAL_PRINCIPALS } from "../auth/route-policy.js";
 import {
   BadRequestError,
@@ -193,9 +192,7 @@ async function handlePlatformConnect(
   }
 
   // Emit signal for connected clients to show the platform login UI
-  await assistantEventHub.publish(
-    buildAssistantEvent({ type: "show_platform_login" }),
-  );
+  broadcastMessage({ type: "show_platform_login" });
 
   return { showPlatformLogin: true };
 }
@@ -259,9 +256,7 @@ async function handlePlatformDisconnect(
   }
 
   // Notify connected clients
-  await assistantEventHub.publish(
-    buildAssistantEvent({ type: "platform_disconnected" }),
-  );
+  broadcastMessage({ type: "platform_disconnected" });
 
   return {
     disconnected: true,

package/src/runtime/routes/playground/__tests__/inject-failures.test.ts

@@ -3,8 +3,8 @@
  */
 import { describe, expect, mock, test } from "bun:test";
 
+import type { AssistantEvent } from "../../../../api/index.js";
 import type { Conversation } from "../../../../daemon/conversation.js";
-import type { ServerMessage } from "../../../../daemon/message-protocol.js";
 
 let _mockConversation: MockConversation | undefined;
 
@@ -18,8 +18,8 @@ mock.module("../../../../context/token-estimator.js", () => ({
 
 mock.module("../helpers.js", () => ({
   getConversationById: async (id: string) => {
-    if (!_mockConversation) return undefined;
-    if (_mockConversation.conversationId !== id) return undefined;
+    if (!_mockConversation) {return undefined;}
+    if (_mockConversation.conversationId !== id) {return undefined;}
     return _mockConversation as unknown as Conversation;
   },
   listConversationsByTitlePrefix: () => [],
@@ -41,13 +41,13 @@ interface MockConversation {
   agentLoop: { compactionCircuit: MockCompactionCircuit };
   contextCompactedMessageCount: number;
   contextCompactedAt: number | null;
-  sentMessages: ServerMessage[];
-  sendToClient: (msg: ServerMessage) => void;
+  sentMessages: AssistantEvent[];
+  sendToClient: (msg: AssistantEvent) => void;
   getMessages: () => unknown[];
 }
 
 function makeConversation(id = "conv-playground-test"): MockConversation {
-  const sentMessages: ServerMessage[] = [];
+  const sentMessages: AssistantEvent[] = [];
   return {
     conversationId: id,
     agentLoop: {
@@ -68,7 +68,7 @@ function findRoute() {
   const route = ROUTES.find(
     (r) => r.operationId === "playgroundInjectCompactionFailures",
   );
-  if (!route) throw new Error("inject-failures route not registered");
+  if (!route) {throw new Error("inject-failures route not registered");}
   return route;
 }
 

package/src/runtime/routes/playground/__tests__/reset-circuit.test.ts

@@ -19,8 +19,8 @@ mock.module("../helpers.js", () => ({
   addPlaygroundMessage: async () => ({ id: "msg-test" }),
 }));
 
+import type { AssistantEvent } from "../../../../api/index.js";
 import type { Conversation } from "../../../../daemon/conversation.js";
-import type { ServerMessage } from "../../../../daemon/message-protocol.js";
 import { RouteError } from "../../errors.js";
 import { ROUTES } from "../index.js";
 
@@ -33,7 +33,7 @@ interface FakeConversationState {
 
 interface FakeConversation {
   conversation: Conversation;
-  sent: ServerMessage[];
+  sent: AssistantEvent[];
   state: FakeConversationState;
 }
 
@@ -47,7 +47,7 @@ function makeFakeConversation(
     contextCompactedAt: null,
     ...overrides,
   };
-  const sent: ServerMessage[] = [];
+  const sent: AssistantEvent[] = [];
   const compactionCircuit = {
     get consecutiveCompactionFailures(): number {
       return state.consecutiveCompactionFailures;
@@ -72,7 +72,7 @@ function makeFakeConversation(
       return state.contextCompactedAt;
     },
     getMessages: () => [],
-    sendToClient: (msg: ServerMessage) => {
+    sendToClient: (msg: AssistantEvent) => {
       sent.push(msg);
     },
   } as unknown as Conversation;
@@ -84,7 +84,7 @@ function findRoute() {
   const route = ROUTES.find(
     (r) => r.operationId === "playgroundResetCompactionCircuit",
   );
-  if (!route) throw new Error("reset-circuit route not registered");
+  if (!route) {throw new Error("reset-circuit route not registered");}
   return route;
 }