@vellumai/assistant 0.6.3 → 0.6.4

package/src/home/relationship-state.ts

@@ -0,0 +1,143 @@
+/**
+ * Relationship state data contract.
+ *
+ * This is the shared wire format that describes the assistant's current
+ * relationship with the user: which tier they're at, what facts the
+ * assistant has learned about them, and which capabilities are unlocked.
+ *
+ * The TypeScript types here are the source of truth. A structurally
+ * identical Swift definition lives at
+ * `clients/shared/Models/RelationshipState.swift` — any change here must
+ * be mirrored there (and the contract test guards the default list).
+ */
+
+export const RELATIONSHIP_STATE_VERSION = 1 as const;
+
+export type RelationshipTier = 1 | 2 | 3 | 4;
+
+export interface TierInfo {
+  label: string;
+  description: string;
+  nextTierHint?: string;
+}
+
+export const TIER_INFO: Record<RelationshipTier, TierInfo> = {
+  1: {
+    label: "Getting to know you",
+    description: "We just met — learning the basics",
+    nextTierHint: "A few more conversations and I'll start to find my footing",
+  },
+  2: {
+    label: "Finding my footing",
+    description: "Starting to understand how you work",
+    nextTierHint: "Keep working with me and we'll hit our stride",
+  },
+  3: {
+    label: "Hitting our stride",
+    description: "We have a real working relationship",
+    nextTierHint:
+      "Give me more context and autonomy and we'll be fully in sync",
+  },
+  4: {
+    label: "In sync",
+    description: "Full partnership",
+  },
+};
+
+export type FactCategory = "voice" | "world" | "priorities";
+export type FactConfidence = "strong" | "uncertain";
+export type FactSource = "onboarding" | "inferred";
+
+export interface Fact {
+  id: string;
+  category: FactCategory;
+  text: string;
+  confidence: FactConfidence;
+  source: FactSource;
+}
+
+export type CapabilityTier = "unlocked" | "next-up" | "earned";
+
+export interface Capability {
+  id: string;
+  name: string;
+  description: string;
+  tier: CapabilityTier;
+  /** Human-readable unlock requirement. */
+  gate: string;
+  /** Shown on "earned" tier: why, not when. */
+  unlockHint?: string;
+  /** Shown on "next-up" tier: e.g. "Connect Google →". */
+  ctaLabel?: string;
+}
+
+export interface RelationshipState {
+  version: typeof RELATIONSHIP_STATE_VERSION;
+  /** Forward-compat for multi-assistant. Only one assistant is supported in v1. */
+  assistantId: string;
+  tier: RelationshipTier;
+  /** 0-100 */
+  progressPercent: number;
+  facts: Fact[];
+  capabilities: Capability[];
+  conversationCount: number;
+  /** ISO 8601 */
+  hatchedDate: string;
+  assistantName: string;
+  userName?: string;
+  /** ISO 8601 */
+  updatedAt: string;
+}
+
+/**
+ * Seed list of capabilities the relationship-state writer should project,
+ * minus the `tier` field (which is computed at write time based on what
+ * the assistant has learned and which integrations are connected).
+ *
+ * Order and ids are part of the public contract — the contract test
+ * asserts this list matches the TDD so drift causes a failure.
+ */
+export const DEFAULT_CAPABILITIES: Omit<Capability, "tier">[] = [
+  {
+    id: "email",
+    name: "Email access",
+    description: "Read, draft, and manage your email",
+    gate: "Connect Google",
+    ctaLabel: "Connect Google →",
+  },
+  {
+    id: "calendar",
+    name: "Calendar awareness",
+    description: "Know your schedule, prep for meetings",
+    gate: "Connect calendar",
+    ctaLabel: "Connect Calendar →",
+  },
+  {
+    id: "slack",
+    name: "Slack monitoring",
+    description: "Watch channels, surface what matters",
+    gate: "Set up Slack app",
+    ctaLabel: "Set up Slack →",
+  },
+  {
+    id: "voice-writing",
+    name: "Write in your voice",
+    description: "Draft messages and docs that sound like you",
+    gate: "Usage — needs conversation history",
+    unlockHint: "I need to learn how you communicate first",
+  },
+  {
+    id: "proactive",
+    name: "Proactive suggestions",
+    description: "Flag things before you ask",
+    gate: "Trust — needs priority understanding",
+    unlockHint: "I need to understand your priorities first",
+  },
+  {
+    id: "autonomous",
+    name: "Act on your behalf",
+    description: "Send messages, file things, take action",
+    gate: "Trust — deepest level",
+    unlockHint: "We need a deeper working relationship first",
+  },
+];

package/src/home/rollup-producer.ts

@@ -0,0 +1,384 @@
+/**
+ * Activity-log roll-up producer for the home feed.
+ *
+ * On a tick, reads the recent `action` items that background jobs have
+ * deposited in the feed (via `emit-feed-event.ts`) and asks the
+ * configured inference provider "consolidate these raw actions into a
+ * small set of digests or threads." This is the replacement for the
+ * old "reflect from nothing" producer: the roll-up starts from real
+ * side effects instead of prompting the model to hallucinate signal
+ * from relationship state alone.
+ *
+ * Mirrors the background-inference pattern established in
+ * `approval-generators.ts`: resolve the provider from config, call
+ * `provider.sendMessage` with a `tool_use`-shaped structured output
+ * schema, validate each returned block, and hand the validated
+ * shapes to `writeAssistantFeedItem`.
+ *
+ * Budget notes:
+ *
+ *   - Hard cap: {@link MAX_ITEMS_PER_ROLLUP} items per tick so a
+ *     single run can never flood the feed.
+ *   - Timeout: {@link ROLLUP_TIMEOUT_MS} so a stalled provider can't
+ *     stall the tick loop.
+ *   - Token budget: {@link ROLLUP_MAX_TOKENS} — tight, because the
+ *     output is a list of short feed items, not a long essay.
+ *   - Input cap: at most {@link MAX_ACTIONS_IN_PROMPT} recent action
+ *     items are serialized into the user prompt. Callers' volume is
+ *     already bounded by the writer's per-source action cap, but
+ *     this second cap protects against pathological inputs.
+ *
+ * Failure modes degrade gracefully: an unavailable provider, a
+ * malformed tool_use block, a schema-rejected item, or an exception
+ * in the inner loop all return a {@link RollupResult} with the
+ * appropriate `skippedReason`. The scheduler logs these but never
+ * surfaces them to the user.
+ */
+
+import { loadConfig } from "../config/loader.js";
+import { getProvider, listProviders } from "../providers/registry.js";
+import type { Provider } from "../providers/types.js";
+import { getLogger } from "../util/logger.js";
+import {
+  writeAssistantFeedItem,
+  type WriteAssistantFeedItemParams,
+} from "./assistant-feed-authoring.js";
+import type { FeedItem } from "./feed-types.js";
+import { readHomeFeed } from "./feed-writer.js";
+import { computeRelationshipState } from "./relationship-state-writer.js";
+
+const log = getLogger("home-feed-rollup");
+
+const ROLLUP_TIMEOUT_MS = 30_000;
+const ROLLUP_MAX_TOKENS = 800;
+const MAX_ITEMS_PER_ROLLUP = 3;
+const MAX_ACTIONS_IN_PROMPT = 30;
+
+const ROLLUP_TOOL_NAME = "write_feed_items";
+
+const ROLLUP_SYSTEM_PROMPT = [
+  "You are a roll-up loop for a personal assistant's home activity feed.",
+  "Raw `action` items land in the feed as a deterministic side effect of background jobs.",
+  "Your job is to CONSOLIDATE those raw actions into higher-signal summary rows — never to invent signal from nothing.",
+  "",
+  "Rules:",
+  "- Emit only `digest` or `thread` items. Do NOT emit `action` items — those come from the background jobs themselves.",
+  "- A `digest` collapses several related raw actions into one summary row (e.g. '3 scheduled jobs ran this morning').",
+  "- A `thread` tracks an ongoing multi-action situation worth surfacing (e.g. 'Outreach to Alice — 2 emails sent, awaiting reply').",
+  "- Each digest/thread must be grounded in specific action items from the list below. Do not invent events.",
+  "- Never duplicate a consolidation that already describes the same set of actions — the writer's one-per-source replacement for digests will collapse repeats but you shouldn't rely on it.",
+  "- Prefer 0 items over low-signal filler. An empty activity log should always produce 0 items.",
+  "- You may emit up to 3 items total.",
+  "",
+  "Use the `write_feed_items` tool to emit items. If nothing is worth rolling up, call the tool with an empty `items` array.",
+].join("\n");
+
+const ROLLUP_TOOL_SCHEMA = {
+  name: ROLLUP_TOOL_NAME,
+  description:
+    "Record the set of roll-up feed items (digests or threads) that consolidate recent activity-log actions. " +
+    "Pass an empty `items` array if nothing is worth rolling up right now.",
+  input_schema: {
+    type: "object" as const,
+    properties: {
+      items: {
+        type: "array",
+        maxItems: MAX_ITEMS_PER_ROLLUP,
+        items: {
+          type: "object",
+          properties: {
+            type: {
+              type: "string",
+              enum: ["digest", "thread"],
+              description:
+                "`digest` collapses multiple related actions into one summary row; `thread` tracks an ongoing multi-action situation.",
+            },
+            source: {
+              type: "string",
+              enum: ["gmail", "slack", "calendar", "assistant"],
+              description:
+                "Origin hint used for the icon. Use `assistant` for cross-source roll-ups of assistant-driven work.",
+            },
+            title: {
+              type: "string",
+              description:
+                "Short headline, 4–10 words. Lowercase-sentence-case, no period.",
+            },
+            summary: {
+              type: "string",
+              description:
+                "One-sentence body copy explaining the roll-up. 1–25 words. Must reference specific actions from the activity log.",
+            },
+            priority: {
+              type: "integer",
+              minimum: 0,
+              maximum: 100,
+              description:
+                "Relative importance (higher = more prominent). Use 70 for digests, 55 for background threads.",
+            },
+            minTimeAway: {
+              type: "integer",
+              minimum: 0,
+              description:
+                "Seconds the user must be away before this item appears. Use 0 for a roll-up the user should see immediately.",
+            },
+          },
+          required: ["type", "title", "summary"],
+          additionalProperties: false,
+        },
+      },
+    },
+    required: ["items"],
+    additionalProperties: false,
+  },
+};
+
+export interface RollupResult {
+  /** Number of items actually written to the feed. */
+  wroteCount: number;
+  /**
+   * When non-null, indicates the producer short-circuited and no LLM
+   * call was made (or the call's result was unusable). The scheduler
+   * logs this but does not treat it as an error.
+   *
+   * `no_actions` means there was nothing to roll up — a quiet but
+   * normal outcome that does not advance the cooldown gate (no point
+   * re-running until new actions land).
+   */
+  skippedReason:
+    | "no_provider"
+    | "no_actions"
+    | "empty_items"
+    | "provider_error"
+    | "malformed_output"
+    | null;
+}
+
+/**
+ * Dependency seams exposed for tests. Production callers pass
+ * `undefined` so the producer uses the real helpers. Tests pass
+ * stubs to avoid `mock.module`, which leaks across files in Bun's
+ * test runner and causes cross-file isolation bugs.
+ */
+export interface RollupProducerDeps {
+  writeItem?: (params: WriteAssistantFeedItemParams) => Promise<unknown>;
+  loadRelationshipState?: () => Promise<
+    Awaited<ReturnType<typeof computeRelationshipState>>
+  >;
+  loadRecentActions?: () => FeedItem[];
+  resolveProvider?: () => Provider | null;
+}
+
+/**
+ * Run one roll-up pass. Loads recent action items from the feed plus
+ * relationship state, builds a user prompt around them, asks the
+ * provider for a `write_feed_items` tool call, and invokes
+ * {@link writeAssistantFeedItem} for each item in the returned array.
+ */
+export async function runRollupProducer(
+  now: Date = new Date(),
+  deps: RollupProducerDeps = {},
+): Promise<RollupResult> {
+  const writeItem = deps.writeItem ?? writeAssistantFeedItem;
+  const loadRelationshipState =
+    deps.loadRelationshipState ?? computeRelationshipState;
+  const loadRecentActions = deps.loadRecentActions ?? defaultLoadRecentActions;
+
+  const provider = deps.resolveProvider
+    ? deps.resolveProvider()
+    : resolveDefaultProvider();
+  if (!provider) {
+    return { wroteCount: 0, skippedReason: "no_provider" };
+  }
+
+  const actions = loadRecentActions();
+  if (actions.length === 0) {
+    return { wroteCount: 0, skippedReason: "no_actions" };
+  }
+
+  const state = await loadRelationshipState();
+  const userPrompt = buildUserPrompt(actions, state, now);
+
+  let response;
+  try {
+    response = await provider.sendMessage(
+      [{ role: "user", content: [{ type: "text", text: userPrompt }] }],
+      [ROLLUP_TOOL_SCHEMA],
+      ROLLUP_SYSTEM_PROMPT,
+      {
+        config: { max_tokens: ROLLUP_MAX_TOKENS },
+        signal: AbortSignal.timeout(ROLLUP_TIMEOUT_MS),
+      },
+    );
+  } catch (err) {
+    log.warn({ err }, "Rollup provider.sendMessage failed");
+    return { wroteCount: 0, skippedReason: "provider_error" };
+  }
+
+  const toolUse = response.content.find(
+    (block) => block.type === "tool_use" && block.name === ROLLUP_TOOL_NAME,
+  );
+  if (!toolUse || toolUse.type !== "tool_use") {
+    return { wroteCount: 0, skippedReason: "malformed_output" };
+  }
+
+  const input = toolUse.input as Record<string, unknown>;
+  const rawItems = Array.isArray(input.items) ? input.items : null;
+  if (!rawItems || rawItems.length === 0) {
+    return { wroteCount: 0, skippedReason: "empty_items" };
+  }
+
+  const capped = rawItems.slice(0, MAX_ITEMS_PER_ROLLUP);
+  const accepted: WriteAssistantFeedItemParams[] = [];
+  for (const raw of capped) {
+    const params = coerceRollupItem(raw);
+    if (params) accepted.push(params);
+  }
+
+  // If the model returned items but every single one failed coercion,
+  // that's a schema-drift signal we want loud in production logs — a
+  // silent "wroteCount: 0, skippedReason: null" would look like a
+  // normal quiet tick and bury the bug. Report it as malformed_output.
+  if (accepted.length === 0) {
+    return { wroteCount: 0, skippedReason: "malformed_output" };
+  }
+
+  let wroteCount = 0;
+  for (const params of accepted) {
+    try {
+      await writeItem(params);
+      wroteCount += 1;
+    } catch (err) {
+      // Schema rejection is a model-output bug, not a regression in the
+      // writer — log and keep going so a single malformed item doesn't
+      // block the rest of the batch.
+      log.warn({ err, params }, "Failed to write rollup item");
+    }
+  }
+
+  return { wroteCount, skippedReason: null };
+}
+
+function resolveDefaultProvider(): ReturnType<typeof getProvider> | null {
+  const config = loadConfig();
+  if (!listProviders().includes(config.services.inference.provider)) {
+    return null;
+  }
+  return getProvider(config.services.inference.provider);
+}
+
+/**
+ * Default recent-actions loader. Reads the TTL-filtered home feed,
+ * keeps only `action` items, and returns them sorted by `createdAt`
+ * descending so the most recent signals land at the top of the
+ * prompt. Non-action items (digests, threads, nudges) are excluded
+ * — the roll-up's input is the raw activity log, not the existing
+ * consolidations.
+ */
+function defaultLoadRecentActions(): FeedItem[] {
+  const feed = readHomeFeed();
+  return feed.items
+    .filter((i) => i.type === "action")
+    .sort((a, b) => {
+      const am = Date.parse(a.createdAt);
+      const bm = Date.parse(b.createdAt);
+      if (Number.isNaN(am) && Number.isNaN(bm)) return 0;
+      if (Number.isNaN(am)) return 1;
+      if (Number.isNaN(bm)) return -1;
+      return bm - am;
+    });
+}
+
+/**
+ * Build the user-prompt context for one roll-up pass. Keeps the
+ * relationship-state block small and bounds the action list at
+ * {@link MAX_ACTIONS_IN_PROMPT} so a pathological input can't blow
+ * the token budget.
+ */
+function buildUserPrompt(
+  actions: FeedItem[],
+  state: Awaited<ReturnType<typeof computeRelationshipState>>,
+  now: Date,
+): string {
+  const actionLines = actions
+    .slice(0, MAX_ACTIONS_IN_PROMPT)
+    .map((a) => {
+      const src = a.source ? `[${a.source}]` : "[-]";
+      return `  - ${a.createdAt} ${src} ${a.title} — ${a.summary}`;
+    })
+    .join("\n");
+
+  const factLines = state.facts
+    .slice(0, 10)
+    .map((f) => `  - ${f.category}: ${f.text}`)
+    .join("\n");
+
+  return [
+    `Current time: ${now.toISOString()}`,
+    `Assistant name: ${state.assistantName}`,
+    state.userName ? `User name: ${state.userName}` : "User name: (unknown)",
+    `Relationship tier: ${state.tier} / 4`,
+    "",
+    `Recent activity log entries (most recent first, up to ${MAX_ACTIONS_IN_PROMPT}):`,
+    actionLines.length > 0 ? actionLines : "  (none)",
+    "",
+    "Known facts about the user (for context only — do NOT invent roll-ups from these):",
+    factLines.length > 0 ? factLines : "  (none yet)",
+    "",
+    "Consolidate the activity log above into a small set of `digest` or `thread` roll-up items. Remember: prefer 0 items over filler, and only roll up when several related actions cluster into a coherent story. Use the `write_feed_items` tool.",
+  ].join("\n");
+}
+
+/**
+ * Coerce a raw tool_use item into
+ * {@link WriteAssistantFeedItemParams}, returning null if the shape is
+ * unrecoverable. The schema on the provider side enforces most of
+ * this, but the runtime check guards against model drift — including
+ * the `type` narrowing to digest/thread (actions and nudges are
+ * rejected here even if the model ignores the tool schema).
+ */
+function coerceRollupItem(
+  raw: unknown,
+): WriteAssistantFeedItemParams | null {
+  if (!raw || typeof raw !== "object") return null;
+  const obj = raw as Record<string, unknown>;
+
+  const type = obj.type;
+  if (type !== "digest" && type !== "thread") {
+    return null;
+  }
+
+  const title = typeof obj.title === "string" ? obj.title.trim() : "";
+  const summary = typeof obj.summary === "string" ? obj.summary.trim() : "";
+  if (!title || !summary) return null;
+
+  const source = obj.source;
+  let coercedSource: WriteAssistantFeedItemParams["source"];
+  if (
+    source === "gmail" ||
+    source === "slack" ||
+    source === "calendar" ||
+    source === "assistant"
+  ) {
+    coercedSource = source;
+  }
+
+  const priority =
+    typeof obj.priority === "number" && Number.isInteger(obj.priority)
+      ? Math.max(0, Math.min(100, obj.priority))
+      : undefined;
+
+  const minTimeAway =
+    typeof obj.minTimeAway === "number" && Number.isInteger(obj.minTimeAway)
+      ? Math.max(0, obj.minTimeAway)
+      : undefined;
+
+  return {
+    type,
+    source: coercedSource,
+    title,
+    summary,
+    priority,
+    minTimeAway,
+  };
+}

package/src/hooks/runner.ts

@@ -49,6 +49,13 @@ export async function runHookScript(
         // @deprecated — usage of VELLUM_ROOT_DIR by hook scripts is deprecated.
         // Removing this requires an LLM-based migration or declarative migration
         // file to update existing user-authored hooks to use VELLUM_WORKSPACE_DIR.
+        //
+        // VELLUM_ROOT_DIR is kept at the legacy `~/.vellum` value even when
+        // vellumRoot() resolves per-instance via BASE_DATA_DIR. User hook
+        // scripts written against this env var expected the legacy path;
+        // changing it would be a silent contract break. Hooks that need the
+        // per-instance root should read BASE_DATA_DIR themselves or use the
+        // new env vars the environment-layout plan adds.
         VELLUM_ROOT_DIR: join(homedir(), ".vellum"),
         VELLUM_WORKSPACE_DIR: getWorkspaceDir(),
         VELLUM_HOOK_SETTINGS: JSON.stringify(

package/src/inbound/platform-callback-registration.ts

@@ -110,12 +110,15 @@ interface RegisterCallbackRouteResponse {
  *   by the platform.
  * @param type - The route type identifier (e.g. "twilio_voice",
  *   "twilio_status", "oauth", "telegram").
+ * @param sourceIdentifier - Optional human-readable source identifier
+ *   (e.g. bot handle, phone number) for display in admin UI.
  * @returns The platform-provided callback URL that external services should use.
  * @throws If the platform request fails.
  */
 export async function registerCallbackRoute(
   callbackPath: string,
   type: string,
+  sourceIdentifier?: string,
 ): Promise<string> {
   const context = await resolvePlatformCallbackRegistrationContext();
   if (!context.enabled || !context.authHeader) {
@@ -134,11 +137,15 @@ export async function registerCallbackRoute(
     Authorization: context.authHeader,
   };
 
-  const body = JSON.stringify({
+  const payload: Record<string, string> = {
     assistant_id: assistantId,
     callback_path: callbackPath,
     type,
-  });
+  };
+  if (sourceIdentifier) {
+    payload.source_identifier = sourceIdentifier;
+  }
+  const body = JSON.stringify(payload);
 
   log.debug({ callbackPath, type }, "Registering platform callback route");
 
@@ -184,6 +191,7 @@ export async function registerCallbackRoute(
  * @param callbackPath - The path to register (e.g. "webhooks/twilio/voice").
  * @param type - The route type identifier.
  * @param queryParams - Optional query parameters to append to the resolved URL.
+ * @param sourceIdentifier - Optional human-readable source identifier for admin display.
  * @returns The resolved callback URL.
  */
 export async function resolveCallbackUrl(
@@ -191,13 +199,14 @@ export async function resolveCallbackUrl(
   callbackPath: string,
   type: string,
   queryParams?: Record<string, string>,
+  sourceIdentifier?: string,
 ): Promise<string> {
   if (!shouldUsePlatformCallbacks()) {
     return directUrl();
   }
 
   try {
-    let url = await registerCallbackRoute(callbackPath, type);
+    let url = await registerCallbackRoute(callbackPath, type, sourceIdentifier);
     if (queryParams && Object.keys(queryParams).length > 0) {
       const params = new URLSearchParams(queryParams);
       const separator = url.includes("?") ? "&" : "?";

package/src/inbound/public-ingress-urls.ts

@@ -120,6 +120,18 @@ export function getTwilioRelayUrl(config: IngressConfig): string {
   return `${wsBase}/webhooks/twilio/relay`;
 }
 
+/**
+ * Build the Twilio media-stream WebSocket URL.
+ * Used for the `<Stream>` TwiML path when the STT provider requires
+ * custom server-side transcription (e.g. OpenAI Whisper).
+ * Converts http:// → ws:// and https:// → wss://.
+ */
+export function getTwilioMediaStreamUrl(config: IngressConfig): string {
+  const base = getPublicBaseUrl(config);
+  const wsBase = base.replace(/^http(s?)/, "ws$1");
+  return `${wsBase}/webhooks/twilio/media-stream`;
+}
+
 /**
  * Build the OAuth callback URL.
  */

package/src/instrument.ts

@@ -52,7 +52,7 @@ export function initSentry(): void {
     dsn,
     release: `vellum-assistant@${APP_VERSION}`,
     dist: COMMIT_SHA,
-    environment: APP_VERSION === "0.0.0-dev" ? "development" : "production",
+    environment: process.env.VELLUM_ENVIRONMENT ?? "production",
     sendDefaultPii: false,
     serverName: hostname(),
     initialScope: {