@vellumai/assistant 0.8.0 → 0.8.2

package/src/runtime/background-job-runner.ts

@@ -0,0 +1,339 @@
+/**
+ * Centralized boundary wrapper for background-conversation jobs.
+ *
+ * `runBackgroundJob()` consolidates the bootstrap → processMessage → timeout
+ * pattern that every background producer (heartbeat, filing, scheduler, memory
+ * consolidation, watcher, update-bulletin, subagent, sequence) has been
+ * open-coding. Wrapping it here lets us:
+ *
+ *  - apply a single timeout policy
+ *  - classify failures uniformly (timeout / model_provider / generic exception)
+ *  - emit a single `activity.failed` notification on any failure path so the
+ *    home feed and native notification surfaces light up automatically
+ *  - never re-throw — the caller always gets a structured result and decides
+ *    whether to alert further
+ *
+ * Producers that have their own bespoke failure UX (e.g. heartbeat's existing
+ * alerter banner) can opt out of the failure-emit via
+ * `suppressFailureNotifications`.
+ */
+
+import type { LLMCallSite } from "../config/schemas/llm.js";
+import { processMessage } from "../daemon/process-message.js";
+import type { TrustContext } from "../daemon/trust-context.js";
+import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
+import { addMessage } from "../memory/conversation-crud.js";
+import type { TitleOrigin } from "../memory/conversation-title-service.js";
+import { emitNotificationSignal } from "../notifications/emit-signal.js";
+import type { AttentionHints } from "../notifications/signal.js";
+import { getLogger } from "../util/logger.js";
+import { hasReceivedUserMessage } from "./pre-first-message-gate.js";
+
+const log = getLogger("background-job-runner");
+
+const DEFAULT_GROUP_ID = "system:background";
+
+/**
+ * Internal-only sentinel for timeouts. Not exported — callers receive a
+ * `errorKind: "timeout"` instead so they don't depend on the class identity.
+ */
+class BackgroundJobTimeoutError extends Error {
+  override name = "BackgroundJobTimeoutError";
+}
+
+export type BackgroundJobErrorKind = "timeout" | "model_provider" | "exception";
+
+export interface RunBackgroundJobOptions {
+  /** Short stable identifier for logs/notifications, e.g. "heartbeat", "filing". */
+  jobName: string;
+  /** Conversation `source` field (free-form, propagated to clients). */
+  source: string;
+  /** Prompt sent as the first message of the conversation. */
+  prompt: string;
+  /**
+   * Short, human-readable hint passed to `bootstrapConversation` for title
+   * generation and as the fallback title. Defaults to `prompt` when omitted,
+   * but callers with multi-paragraph prompts should supply a concise label
+   * (e.g. `"Knowledge base filing"`) — otherwise a fallback title would echo
+   * the entire prompt and title-generation requests waste tokens.
+   */
+  systemHint?: string;
+  /** Trust context applied to the agent turn. */
+  trustContext: TrustContext;
+  /** LLM call-site identifier — drives provider/model/effort/etc. resolution. */
+  callSite: LLMCallSite;
+  /** Hard timeout for `processMessage` in milliseconds. */
+  timeoutMs: number;
+  /**
+   * When true, failures do NOT emit an `activity.failed` notification.
+   * Use for jobs that own their own failure UX (e.g. heartbeat's alerter)
+   * or for "quiet" scheduled jobs that the user has explicitly asked to
+   * suppress notifications for.
+   */
+  suppressFailureNotifications?: boolean;
+  /** Conversation grouping id. Defaults to `"system:background"`. */
+  groupId?: string;
+  /** Title origin tag for `bootstrapConversation`. */
+  origin: TitleOrigin;
+  /** Conversation type to bootstrap with. Defaults to `"background"`. */
+  conversationType?: "background" | "scheduled";
+  /**
+   * Schedule job id to associate with the conversation row. Only meaningful
+   * for `conversationType: "scheduled"` — propagated so schedule cleanup and
+   * sidebar grouping can find the conversation by job id.
+   */
+  scheduleJobId?: string;
+  /**
+   * Fires synchronously after `bootstrapConversation` returns and BEFORE
+   * `processMessage` starts. Use this to populate the macOS sidebar entry
+   * immediately (the SSE event fires when the job starts) rather than after
+   * the job finishes (which can be up to `timeoutMs` later for long jobs).
+   *
+   * Wrapped in try/catch internally — a callback throw is logged and
+   * swallowed so it cannot kill the job runner.
+   */
+  onConversationCreated?: (conversationId: string) => void;
+  /**
+   * Opt out of the "skip until first user message" gate. Defaults to
+   * `false` (gate active). Set to `true` ONLY for jobs that genuinely need
+   * to run pre-onboarding — there are currently none, but the escape hatch
+   * exists so the gate can be tightened without trapping a future caller.
+   *
+   * The gate prevents warm-pool images from generating ghost failure rows
+   * before the user ever sees the assistant. See `pre-first-message-gate.ts`.
+   */
+  allowPreFirstUserMessage?: boolean;
+  /**
+   * Optional prompt-injection mitigation. When set, the runner adds three
+   * messages to the conversation BEFORE invoking `processMessage`:
+   *
+   *   1. `user` role: `preamble`     — static, trusted instructions.
+   *   2. `assistant` role: `content` — attacker-controllable payload (the LLM
+   *      treats it as its own past output, not as user instructions).
+   *   3. `user` role: `postamble`    — static, trusted action prompt.
+   *
+   * `processMessage` is then invoked with whatever `prompt` the caller set
+   * (often empty or a short kicker) since the conversation already carries
+   * the seed.
+   *
+   * Used by the watcher engine to ingest external provider events safely:
+   * a malicious Linear title or Gmail subject reaches the model only in
+   * the `assistant` role and cannot override the action prompt.
+   */
+  assistantSandwich?: { preamble: string; content: string; postamble: string };
+}
+
+export interface RunBackgroundJobResult {
+  conversationId: string;
+  ok: boolean;
+  error?: Error;
+  errorKind?: BackgroundJobErrorKind;
+  /**
+   * Set when the runner declined to execute. Callers can distinguish a
+   * skipped job from a successful one even though both report `ok: true`.
+   *
+   * - `"pre_first_user_message"`: gate tripped — daemon has not yet seen
+   *   any user-authored message in a standard conversation. No conversation
+   *   was bootstrapped; `conversationId` is the empty string.
+   */
+  skipReason?: "pre_first_user_message";
+}
+
+function classifyError(err: unknown): BackgroundJobErrorKind {
+  if (err instanceof BackgroundJobTimeoutError) return "timeout";
+  if (!(err instanceof Error)) return "exception";
+
+  const ctorName = err.constructor?.name ?? "";
+  const { message } = err;
+
+  if (
+    ctorName.includes("Anthropic") ||
+    ctorName.includes("OpenAI") ||
+    /\brate\b/i.test(message) ||
+    /\b5xx\b/i.test(message) ||
+    /\b401\b/.test(message) ||
+    /\b403\b/.test(message)
+  ) {
+    return "model_provider";
+  }
+
+  return "exception";
+}
+
+/**
+ * Run a background conversation job with timeout, error classification, and
+ * (by default) failure notification emission. Never re-throws.
+ */
+export async function runBackgroundJob(
+  opts: RunBackgroundJobOptions,
+): Promise<RunBackgroundJobResult> {
+  // Gate: refuse to bootstrap a conversation until the user has interacted
+  // at least once. Warm-pool images would otherwise produce "Background job
+  // failed" rows visible in the sidebar the moment a real user hatches the
+  // assistant — see `pre-first-message-gate.ts` for the rationale.
+  //
+  // Service-level callers (heartbeat, update-bulletin) are expected to gate
+  // earlier and never reach this point; reaching the gate here means a
+  // caller either forgot to gate or deliberately opted in via
+  // `allowPreFirstUserMessage`. We log at `info` (not `warn`) because the
+  // expected steady state is "no calls reach here once onboarding is done."
+  if (!opts.allowPreFirstUserMessage && !hasReceivedUserMessage()) {
+    log.info(
+      { jobName: opts.jobName, source: opts.source },
+      "Background job skipped — daemon has not received a first user message yet",
+    );
+    return {
+      ok: true,
+      conversationId: "",
+      skipReason: "pre_first_user_message",
+    };
+  }
+
+  let conversation: ReturnType<typeof bootstrapConversation> | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    // Bootstrap inside the try so that a `createConversation` /
+    // `queueGenerateConversationTitle` failure is caught and surfaced as a
+    // structured `{ ok: false }` result rather than re-thrown to the caller —
+    // the documented contract of this runner.
+    conversation = bootstrapConversation({
+      conversationType: opts.conversationType ?? "background",
+      source: opts.source,
+      origin: opts.origin,
+      systemHint: opts.systemHint ?? opts.prompt,
+      groupId: opts.groupId ?? DEFAULT_GROUP_ID,
+      ...(opts.scheduleJobId ? { scheduleJobId: opts.scheduleJobId } : {}),
+    });
+
+    // Fire the sidebar-creation callback synchronously after bootstrap so
+    // connected clients (macOS sidebar, etc.) see the conversation appear
+    // immediately rather than after `processMessage` returns. Wrapped so a
+    // callback throw cannot abort the job.
+    if (opts.onConversationCreated) {
+      try {
+        opts.onConversationCreated(conversation.id);
+      } catch (cbErr) {
+        log.warn(
+          {
+            err: cbErr instanceof Error ? cbErr.message : String(cbErr),
+            jobName: opts.jobName,
+            conversationId: conversation.id,
+          },
+          "onConversationCreated callback threw; continuing job",
+        );
+      }
+    }
+
+    // SECURITY: Optional anti-injection sandwich. Attacker-controllable data
+    // is wrapped in an assistant-role message between two static user-role
+    // messages. The LLM treats assistant-role content as its own prior
+    // output, not as user instructions, so a malicious payload (e.g. a
+    // crafted Linear title) cannot override the postamble's action prompt.
+    if (opts.assistantSandwich) {
+      await addMessage(
+        conversation.id,
+        "user",
+        opts.assistantSandwich.preamble,
+        undefined,
+        { skipIndexing: true },
+      );
+      await addMessage(
+        conversation.id,
+        "assistant",
+        opts.assistantSandwich.content,
+        undefined,
+        { skipIndexing: true },
+      );
+      await addMessage(
+        conversation.id,
+        "user",
+        opts.assistantSandwich.postamble,
+        undefined,
+        { skipIndexing: true },
+      );
+    }
+
+    const work = processMessage(conversation.id, opts.prompt, undefined, {
+      trustContext: opts.trustContext,
+      callSite: opts.callSite,
+    });
+    // Absorb late rejections: if the timeout wins the race, `work` keeps
+    // running and may eventually reject — swallow so it doesn't surface as
+    // an unhandled rejection.
+    work.catch(() => {});
+
+    const timeout = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        reject(
+          new BackgroundJobTimeoutError(
+            `Background job '${opts.jobName}' timed out after ${opts.timeoutMs}ms`,
+          ),
+        );
+      }, opts.timeoutMs);
+    });
+
+    await Promise.race([work, timeout]);
+    return { conversationId: conversation.id, ok: true };
+  } catch (err) {
+    const errorKind = classifyError(err);
+    const error = err instanceof Error ? err : new Error(String(err));
+    // Bootstrap can fail before `conversation` is assigned; fall back to ""
+    // so the structured failure result still flows to the caller.
+    const conversationId = conversation?.id ?? "";
+
+    log.error(
+      {
+        err: error.message,
+        errorKind,
+        jobName: opts.jobName,
+        conversationId,
+      },
+      "Background job failed",
+    );
+
+    if (!opts.suppressFailureNotifications) {
+      const hints: AttentionHints = {
+        requiresAction: false,
+        urgency: "medium",
+        isAsyncBackground: true,
+        visibleInSourceNow: false,
+      };
+      // Dedupe by jobName + UTC date so repeated failures of the same
+      // background job (e.g. a watcher whose credentials are revoked)
+      // collapse into a single home-feed entry per day rather than
+      // spamming on every tick.
+      const day = new Date().toISOString().slice(0, 10);
+      const dedupeKey = `activity-failed:${opts.jobName}:${day}`;
+      emitNotificationSignal({
+        sourceChannel: "assistant_tool",
+        sourceContextId: conversationId,
+        sourceEventName: "activity.failed",
+        dedupeKey,
+        contextPayload: {
+          jobName: opts.jobName,
+          errorMessage: error.message,
+          errorKind,
+        },
+        attentionHints: hints,
+      }).catch((emitErr) => {
+        log.warn(
+          {
+            err: emitErr instanceof Error ? emitErr.message : String(emitErr),
+            jobName: opts.jobName,
+            conversationId,
+          },
+          "Failed to emit activity.failed notification for background job",
+        );
+      });
+    }
+
+    return {
+      conversationId,
+      ok: false,
+      error,
+      errorKind,
+    };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}

package/src/runtime/btw-sidechain.ts

@@ -70,12 +70,15 @@ export async function runBtwSidechain(
   const tools = params.tools;
   const history = params.messages ?? params.conversation?.getMessages() ?? [];
   const messages = [...history, userMessage(trimmedContent)];
+  // Side-chains force `tool_choice: { type: "none" }` below, so tool usage
+  // guidance must stay in tool descriptions rather than this system prompt.
   const systemPrompt =
     params.systemPrompt ??
     (params.conversation?.hasSystemPromptOverride
       ? params.conversation.systemPrompt
       : buildSystemPrompt({
           excludeBootstrap: true,
+          excludeCustomPrefix: true,
           userPersona: params.userPersona,
           channelPersona: params.channelPersona,
           userSlug: params.userSlug,

package/src/runtime/http-router.ts

@@ -18,7 +18,7 @@ import { httpError } from "./http-errors.js";
 import { withErrorHandling } from "./middleware/error-handler.js";
 import { routeDefinitionsToHTTPRoutes } from "./routes/http-adapter.js";
 import { ROUTES } from "./routes/index.js";
-import type { RoutePathParam } from "./routes/types.js";
+import type { RouteLoggingConfig, RoutePathParam } from "./routes/types.js";
 
 // ---------------------------------------------------------------------------
 // Route definition types
@@ -128,6 +128,11 @@ export interface HTTPRouteDefinition {
   responseStatus?: string;
   /** Additional response codes documented in the generated OpenAPI spec. */
   additionalResponses?: Record<string, RouteAdditionalResponse>;
+  /**
+   * Per-route request-log control. See `RouteLoggingConfig` in `routes/types.ts`.
+   * When omitted, the route uses the default log-every-request behavior.
+   */
+  logging?: RouteLoggingConfig;
 }
 
 // ---------------------------------------------------------------------------
@@ -155,6 +160,36 @@ export class HttpRouter {
     }
   }
 
+  /**
+   * Resolve the request-logging metadata for an incoming request without
+   * invoking the handler. Returns the matched route's logging config plus
+   * a stable counter key derived from operationId (or method+endpoint as
+   * a fallback when operationId is not set).
+   *
+   * Called by the HTTP server *before* `withRequestLogging` so the
+   * middleware can decide whether to suppress the per-request success log.
+   * Returns `null` when no route matches or the matched route opts out of
+   * custom logging — both cases mean "use the default log-every-request".
+   */
+  findLoggingMetadata(
+    method: string,
+    endpoint: string,
+  ): { counterKey: string; config: RouteLoggingConfig } | null {
+    const normalized = endpoint.endsWith("/")
+      ? endpoint.slice(0, -1)
+      : endpoint;
+    for (const compiled of this.compiledRoutes) {
+      if (compiled.def.method !== method) continue;
+      if (!compiled.regex.test(normalized)) continue;
+      const config = compiled.def.logging;
+      if (!config) return null;
+      const counterKey =
+        compiled.def.operationId ?? `${method} ${compiled.def.endpoint}`;
+      return { counterKey, config };
+    }
+    return null;
+  }
+
   /**
    * Dispatch a request to the matching route handler.
    *

package/src/runtime/http-server.ts

@@ -86,6 +86,10 @@ import {
 } from "./routes/channel-guardian-routes.js";
 import { RouteError } from "./routes/errors.js";
 import { handleHealth, handleReadyz } from "./routes/identity-routes.js";
+import {
+  startInferenceProfileSessionReaper,
+  stopInferenceProfileSessionReaper,
+} from "./routes/inference-profile-session-reaper.js";
 import { matchSkillRoute } from "./skill-route-registry.js";
 
 // Re-export for consumers
@@ -492,12 +496,16 @@ export class RuntimeHttpServer {
 
     startCanonicalGuardianExpirySweep();
     log.info("Canonical guardian request expiry sweep started");
+
+    startInferenceProfileSessionReaper();
+    log.info("Inference profile session reaper started");
   }
 
   async stop(): Promise<void> {
     stopGuardianExpirySweep();
     stopGuardianActionSweep();
     stopCanonicalGuardianExpirySweep();
+    stopInferenceProfileSessionReaper();
     if (this.retrySweepTimer) {
       clearInterval(this.retrySweepTimer);
       this.retrySweepTimer = null;
@@ -531,7 +539,9 @@ export class RuntimeHttpServer {
     server: ReturnType<typeof Bun.serve>,
   ): Promise<Response> {
     server.timeout(req, 1800);
-    // Skip request logging for health-check probes to reduce log noise.
+    // Skip request logging entirely for the bare-bones liveness/readiness
+    // probes Bun's load balancer hits — these don't go through the
+    // declarative router and would just clutter logs unconditionally.
     const url = new URL(req.url);
     if (
       (url.pathname === "/healthz" || url.pathname === "/readyz") &&
@@ -539,7 +549,22 @@ export class RuntimeHttpServer {
     ) {
       return this.routeRequest(req, server);
     }
-    return withRequestLogging(req, () => this.routeRequest(req, server));
+    // Ask the router for any per-route logging policy *before* dispatching,
+    // so the middleware can decide whether to suppress the success log
+    // line for noisy probes (e.g. macOS app polling /v1/health every few
+    // seconds). Only `/v1/*` paths are registered with the declarative
+    // router; for everything else `meta` stays undefined and the middleware
+    // falls back to its default log-every-request behavior.
+    let meta;
+    if (url.pathname.startsWith("/v1/")) {
+      const endpoint = url.pathname.slice("/v1/".length).replace(/\/$/, "");
+      meta = this.router.findLoggingMetadata(req.method, endpoint) ?? undefined;
+    }
+    return withRequestLogging(
+      req,
+      () => this.routeRequest(req, server),
+      meta,
+    );
   }
 
   private async routeRequest(
@@ -557,7 +582,6 @@ export class RuntimeHttpServer {
       return handleReadyz();
     }
 
-
     // WebSocket upgrade for ConversationRelay — before auth check because
     // Twilio WebSocket connections don't use bearer tokens.
     if (
@@ -623,6 +647,7 @@ export class RuntimeHttpServer {
             err.code as HttpErrorCode,
             err.message,
             err.statusCode,
+            err.details,
           );
         }
         throw err;
@@ -1013,8 +1038,9 @@ export class RuntimeHttpServer {
     ws: ServerWebSocket<LiveVoiceWebSocketData>,
     frame: LiveVoiceServerFrame,
   ): void {
-    ws.data.lastSeq = Math.max(ws.data.lastSeq, frame.seq);
-    ws.send(JSON.stringify(frame));
+    const seq = Math.max(ws.data.lastSeq + 1, frame.seq);
+    ws.data.lastSeq = seq;
+    ws.send(JSON.stringify({ ...frame, seq }));
   }
 
   private releaseLiveVoiceSession(

package/src/runtime/http-types.ts

@@ -115,6 +115,11 @@ export interface RuntimeMessageConversationOptions {
   commandIntent?: { type: string; payload?: string; languageCode?: string };
   /** Slack-only non-persisted notice injected into the active model turn. */
   slackRuntimeContextNotice?: string;
+  /**
+   * Persisted user-facing content. When present, storage/UI use this value
+   * while the model-facing turn continues to use `content`.
+   */
+  displayContent?: string;
   /** Optional callback to receive real-time agent loop events (text deltas, tool starts, etc.). */
   onEvent?: (msg: ServerMessage) => void;
   /**
@@ -191,6 +196,8 @@ export interface RuntimeAttachmentMetadata {
 
 export interface RuntimeMessagePayload {
   id: string;
+  /** Concrete persisted assistant row id for row-scoped actions. */
+  daemonMessageId?: string;
   role: string;
   content: string;
   timestamp: string;
@@ -225,5 +232,19 @@ export interface RuntimeMessagePayload {
     status: string;
     error?: string;
     conversationId?: string;
+    objective?: string;
+  };
+  slackMessage?: {
+    channelId: string;
+    channelTs: string;
+    threadTs?: string;
+    messageLink?: {
+      appUrl?: string;
+      webUrl?: string;
+    };
+    threadLink?: {
+      appUrl?: string;
+      webUrl?: string;
+    };
   };
 }