@vellumai/assistant 0.6.5 → 0.7.0

package/src/memory/v2/sweep-job.ts

@@ -0,0 +1,298 @@
+/**
+ * Memory v2 — `memory_v2_sweep` job handler.
+ *
+ * The sweep is the auto-extraction analog of v1's `graph_extract`: idle-
+ * debounced, prompted with the current `memory/buffer.md` so it dedupes
+ * against entries `remember()` already wrote, and asked to surface anything
+ * the assistant should have remembered but missed. Each returned entry is
+ * appended to `memory/buffer.md` and `memory/archive/<today>.md` using the
+ * exact same write path as `remember()` so consolidation can't tell which
+ * entries came from the model and which came from the tool call.
+ *
+ * Lifecycle integration: scheduled by PR 24's hook into the existing
+ * extraction-trigger path. Until then this handler is invoked only by
+ * `memory_v2_sweep` rows enqueued explicitly (tests, future CLI).
+ *
+ * Skipped entirely when the `memory-v2-enabled` feature flag is off, or when
+ * `config.memory.v2.sweep_enabled` is false — keeps the sweep dormant in
+ * v1-only workspaces and in v2 workspaces that haven't opted in, even if a
+ * stale row sits in the queue at flag-flip time.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { desc, gt } from "drizzle-orm";
+import { z } from "zod";
+
+import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
+import type { AssistantConfig } from "../../config/types.js";
+import { getAssistantName } from "../../daemon/identity-helpers.js";
+import {
+  extractToolUse,
+  getConfiguredProvider,
+  userMessage,
+} from "../../providers/provider-send-message.js";
+import type { ToolDefinition } from "../../providers/types.js";
+import { getLogger } from "../../util/logger.js";
+import { getWorkspaceDir } from "../../util/platform.js";
+import { getDb } from "../db-connection.js";
+import {
+  appendBufferAndArchive,
+  formatRememberEntry,
+} from "../graph/tool-handlers.js";
+import type { MemoryJob } from "../jobs-store.js";
+import { messages } from "../schema.js";
+import { renderSweepPrompt } from "./prompts/sweep.js";
+
+const log = getLogger("memory-v2-sweep");
+
+/** Window of conversation history the sweep inspects on each run. */
+const RECENT_MESSAGES_WINDOW_MS = 30 * 60 * 1000;
+
+/**
+ * Cap on the message text we hand the model. Recent-messages text is the
+ * single-largest input — clamping keeps the request under typical context
+ * windows without having to compute precise token counts.
+ */
+const MAX_RECENT_TEXT_CHARS = 32_000;
+
+/**
+ * Cap on the buffer text we hand the model. The buffer can grow large in
+ * busy workspaces; the model only needs enough to dedupe, not the entire
+ * archive.
+ */
+const MAX_BUFFER_CHARS = 16_000;
+
+// Tool-call schema. The JSON schema is what the provider sees; the Zod
+// schema below validates the model's reply at runtime since the SDK
+// returns the tool input as `unknown`. The two must stay in sync.
+const SWEEP_TOOL_NAME = "emit_remember_entries";
+
+const SWEEP_TOOL: ToolDefinition = {
+  name: SWEEP_TOOL_NAME,
+  description:
+    "Emit zero or more remember()-style entries the assistant should commit to long-term memory.",
+  input_schema: {
+    type: "object",
+    properties: {
+      entries: {
+        type: "array",
+        description:
+          "Each entry is a single line in the assistant's first-person voice (e.g. 'Alice prefers VS Code over Vim').",
+        items: { type: "string" },
+      },
+    },
+    required: ["entries"],
+  },
+};
+
+const SweepResultSchema = z.object({
+  entries: z.array(z.string()),
+});
+
+/**
+ * Job handler. Reads recent messages + buffer, asks the configured provider
+ * for additional remember-able entries, and appends each entry to
+ * `memory/buffer.md` + `memory/archive/<today>.md` via the same helper
+ * `remember()` uses.
+ *
+ * Returns the number of entries written so callers (and tests) can assert
+ * progress without inspecting the filesystem.
+ */
+export async function memoryV2SweepJob(
+  _job: MemoryJob,
+  config: AssistantConfig,
+): Promise<number> {
+  if (!isAssistantFeatureFlagEnabled("memory-v2-enabled", config)) {
+    log.debug("memory-v2-enabled flag off; sweep skipped");
+    return 0;
+  }
+
+  if (!config.memory?.v2?.sweep_enabled) {
+    log.debug("memory.v2.sweep_enabled is false; sweep skipped");
+    return 0;
+  }
+
+  const workspaceDir = getWorkspaceDir();
+  const memoryDir = join(workspaceDir, "memory");
+  const recentText = loadRecentMessagesText(Date.now());
+  if (!recentText) {
+    log.debug("No recent messages in window; sweep skipped");
+    return 0;
+  }
+
+  const existingBuffer = readBufferText(memoryDir);
+
+  const provider = await getConfiguredProvider("memoryV2Sweep");
+  if (!provider) {
+    log.warn("memoryV2Sweep provider unavailable; sweep skipped");
+    return 0;
+  }
+
+  const systemPrompt = renderSweepPrompt({
+    assistantName: getAssistantName(),
+    userName: resolveUserName(workspaceDir),
+  });
+  const userText =
+    `## existingBuffer\n\n${existingBuffer || "(empty)"}\n\n` +
+    `## recentMessages\n\n${recentText}`;
+
+  const response = await provider.sendMessage(
+    [userMessage(userText)],
+    [SWEEP_TOOL],
+    systemPrompt,
+    {
+      config: {
+        callSite: "memoryV2Sweep" as const,
+        tool_choice: { type: "tool" as const, name: SWEEP_TOOL_NAME },
+      },
+    },
+  );
+
+  const toolBlock = extractToolUse(response);
+  if (!toolBlock || toolBlock.name !== SWEEP_TOOL_NAME) {
+    log.debug("Sweep model returned no tool_use block");
+    return 0;
+  }
+  const parsed = SweepResultSchema.safeParse(toolBlock.input);
+  if (!parsed.success) {
+    log.warn(
+      { error: parsed.error.message },
+      "Sweep tool input did not match schema",
+    );
+    return 0;
+  }
+
+  const written = appendEntries(memoryDir, parsed.data.entries);
+  if (written > 0) {
+    log.info({ written }, "Memory v2 sweep wrote new buffer entries");
+  }
+  return written;
+}
+
+/**
+ * Append each non-empty entry to `memory/buffer.md` + today's archive,
+ * using the same format `remember()` produces. Returns the count of entries
+ * actually written (empties and whitespace-only strings are skipped so the
+ * model can't pad the response).
+ */
+function appendEntries(memoryDir: string, entries: string[]): number {
+  let written = 0;
+  for (const raw of entries) {
+    const content = typeof raw === "string" ? raw.trim() : "";
+    if (!content) continue;
+    const now = new Date();
+    const entry = formatRememberEntry(content, now);
+    appendBufferAndArchive({ rootDir: memoryDir, entry, now });
+    written += 1;
+  }
+  return written;
+}
+
+/**
+ * Read `memory/buffer.md` and return its contents, capped at
+ * `MAX_BUFFER_CHARS`. Missing file → empty string. The cap keeps the dedup
+ * signal manageable; we slice from the *end* of the file so the most recent
+ * entries always survive.
+ */
+function readBufferText(memoryDir: string): string {
+  let text: string;
+  try {
+    text = readFileSync(join(memoryDir, "buffer.md"), "utf-8");
+  } catch {
+    return "";
+  }
+  if (text.length <= MAX_BUFFER_CHARS) return text;
+  return text.slice(text.length - MAX_BUFFER_CHARS);
+}
+
+/**
+ * Pull recent messages from every conversation in the window, formatted
+ * as `[role]: content` lines so the model can follow the back-and-forth.
+ *
+ * Bounded by `MAX_RECENT_TEXT_CHARS` — when the window is busier than the
+ * cap, the *oldest* messages are dropped (truncate-from-front) so the model
+ * always sees the latest context.
+ */
+function loadRecentMessagesText(nowMs: number): string {
+  const cutoff = nowMs - RECENT_MESSAGES_WINDOW_MS;
+  const db = getDb();
+  // Pull newest-first then reverse for chronological output. Bounding the
+  // initial limit (1000) defends against pathological busy windows where a
+  // naive scan would touch every recent message.
+  const rows = db
+    .select({
+      role: messages.role,
+      content: messages.content,
+    })
+    .from(messages)
+    .where(gt(messages.createdAt, cutoff))
+    .orderBy(desc(messages.createdAt))
+    .limit(1000)
+    .all();
+  if (rows.length === 0) return "";
+
+  const lines: string[] = [];
+  for (const row of rows) {
+    const text = stringifyMessageContent(row.content);
+    if (!text) continue;
+    lines.push(`[${row.role}]: ${text}`);
+  }
+  if (lines.length === 0) return "";
+
+  // Reverse so the oldest message lands first — natural reading order.
+  lines.reverse();
+  let joined = lines.join("\n\n");
+  if (joined.length > MAX_RECENT_TEXT_CHARS) {
+    joined = joined.slice(joined.length - MAX_RECENT_TEXT_CHARS);
+  }
+  return joined;
+}
+
+/**
+ * Coerce stored message content (JSON-serialized `ContentBlock[]` *or* plain
+ * string in legacy rows) into a single text string. Image / tool blocks are
+ * dropped — the sweep model only needs the spoken context.
+ */
+function stringifyMessageContent(stored: string): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stored);
+  } catch {
+    return stored.trim();
+  }
+  if (typeof parsed === "string") return parsed.trim();
+  if (!Array.isArray(parsed)) return "";
+  const parts: string[] = [];
+  for (const block of parsed) {
+    if (
+      block &&
+      typeof block === "object" &&
+      (block as { type?: string }).type === "text" &&
+      typeof (block as { text?: unknown }).text === "string"
+    ) {
+      parts.push((block as { text: string }).text);
+    }
+  }
+  return parts.join("\n").trim();
+}
+
+/**
+ * Read the guardian's display name from `users/default.md`. We look for the
+ * markdown-bold "Name" label (matching the IDENTITY.md convention) and fall
+ * back to `null` on any miss; the prompt template substitutes a generic
+ * label.
+ */
+function resolveUserName(workspaceDir: string): string | null {
+  try {
+    const content = readFileSync(
+      join(workspaceDir, "users", "default.md"),
+      "utf-8",
+    );
+    const match = content.match(/\*\*Name:\*\*\s*(.+)/);
+    return match?.[1]?.trim() || null;
+  } catch {
+    return null;
+  }
+}

package/src/memory/v2/types.ts

@@ -0,0 +1,116 @@
+// ---------------------------------------------------------------------------
+// Memory v2 — Shared types
+// ---------------------------------------------------------------------------
+//
+// Types shared across the v2 memory subsystem. Most values here cross a
+// serialization boundary — YAML frontmatter, on-disk JSON, or a SQLite JSON
+// column — so they ship as Zod schemas with inferred TypeScript types so
+// runtime validation runs wherever they are read. The skill-autoinjection
+// entry stays a plain `interface` because it is purely in-process.
+//
+// This file must not import from any other `memory/v2/*` module — it is the
+// leaf of the v2 dependency graph.
+
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Concept pages
+// ---------------------------------------------------------------------------
+
+/**
+ * YAML frontmatter at the top of a concept page (`memory/concepts/<slug>.md`).
+ *
+ * `edges` is a derived view of `memory/edges.json` — it is regenerated by
+ * the rebuild-edges backfill job and is not the source of truth for the graph
+ * topology. `ref_files` lists paths to attached media (images, audio, etc.).
+ */
+export const ConceptPageFrontmatterSchema = z.object({
+  edges: z.array(z.string()).default([]),
+  ref_files: z.array(z.string()).default([]),
+});
+
+export type ConceptPageFrontmatter = z.infer<
+  typeof ConceptPageFrontmatterSchema
+>;
+
+/**
+ * A single concept page on disk. The slug is the filename minus `.md` and
+ * also the stable identity used in edges and activation state.
+ */
+export const ConceptPageSchema = z.object({
+  slug: z.string(),
+  frontmatter: ConceptPageFrontmatterSchema,
+  body: z.string(),
+});
+
+export type ConceptPage = z.infer<typeof ConceptPageSchema>;
+
+// ---------------------------------------------------------------------------
+// Edges index (`memory/edges.json`)
+// ---------------------------------------------------------------------------
+
+/**
+ * Source of truth for v2 graph topology. Edges are unweighted, undirected,
+ * and stored as canonicalized 2-tuples (alphabetical-first slug first).
+ */
+export const EdgesIndexSchema = z.object({
+  version: z.literal(1),
+  edges: z.array(z.tuple([z.string(), z.string()])),
+});
+
+export type EdgesIndex = z.infer<typeof EdgesIndexSchema>;
+
+// ---------------------------------------------------------------------------
+// Activation state (per-conversation, persisted in SQLite)
+// ---------------------------------------------------------------------------
+
+/**
+ * One entry in the per-conversation `everInjected` list. Tracks which
+ * concept-page slug was injected on which turn so compaction can selectively
+ * evict slugs whose attachments lived on compacted turns.
+ */
+export const EverInjectedEntrySchema = z.object({
+  slug: z.string(),
+  turn: z.number().int().nonnegative(),
+});
+
+export type EverInjectedEntry = z.infer<typeof EverInjectedEntrySchema>;
+
+/**
+ * Snapshot of memory v2 retrieval state for a single conversation.
+ *
+ * `state` is a sparse map of slug → activation in [0, 1]; only slugs above
+ * `epsilon` are persisted. `everInjected` is the running list of slugs the
+ * assistant has already attached to a user message, used to make injection
+ * append-only and cache-stable.
+ */
+export const ActivationStateSchema = z.object({
+  messageId: z.string(),
+  state: z.record(z.string(), z.number()),
+  everInjected: z.array(EverInjectedEntrySchema),
+  currentTurn: z.number().int().nonnegative(),
+  updatedAt: z.number().int().nonnegative(),
+});
+
+export type ActivationState = z.infer<typeof ActivationStateSchema>;
+
+// ---------------------------------------------------------------------------
+// Skill autoinjection (synthetic in-memory entries, not on-disk pages)
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-skill capability snapshot held in-process and embedded into the
+ * `memory_v2_skills` Qdrant collection. `content` is the rendered
+ * `buildSkillContent` string — already capped at 500 chars upstream and
+ * already containing the skill's display name — and is what we embed and
+ * what we render verbatim in `### Skills You Can Use`.
+ *
+ * Plain interface (no Zod) because skill data does not cross a
+ * serialization boundary: it is built in-process by `seedV2SkillEntries`
+ * and read in-process by `renderInjectionBlock`. The Qdrant payload is
+ * not parsed back through this type.
+ */
+export interface SkillEntry {
+  id: string;
+  content: string;
+}

package/src/memory/validation.ts

@@ -5,7 +5,7 @@ import { z } from "zod";
  * Coerces out-of-range numbers to the nearest bound rather than rejecting,
  * since LLM-generated values occasionally exceed the range.
  */
-export const unitInterval = z
+const unitInterval = z
   .number()
   .transform((v) => Math.min(1, Math.max(0, v)));
 

package/src/messaging/providers/index.ts

@@ -0,0 +1,262 @@
+/**
+ * Direct channel delivery — bypasses the gateway HTTP proxy.
+ *
+ * Each channel that supports direct delivery registers its callback-URL
+ * matcher and send logic here.  The gateway-client consults
+ * `isDirectDelivery()` before falling back to the HTTP proxy path.
+ *
+ * Currently supported: WhatsApp, Telegram, Slack.
+ */
+
+import type {
+  ChannelDeliveryResult,
+  ChannelReplyPayload,
+} from "@vellumai/gateway-client";
+import { ChannelDeliveryError } from "@vellumai/gateway-client/http-delivery";
+
+import { getLogger } from "../../util/logger.js";
+import {
+  sendSlackAssistantThreadStatus,
+  sendSlackAttachments,
+  sendSlackReaction,
+  sendSlackReply,
+  sendSlackTypingIndicator,
+} from "./slack/send.js";
+import {
+  sendTelegramAttachments,
+  sendTelegramReply,
+  sendTelegramTypingIndicator,
+} from "./telegram-bot/send.js";
+import { sendWhatsAppAttachments, sendWhatsAppReply } from "./whatsapp/send.js";
+
+const log = getLogger("direct-delivery");
+
+// ---------------------------------------------------------------------------
+// Callback-URL matchers
+// ---------------------------------------------------------------------------
+
+function matchesPathname(callbackUrl: string, pathname: string): boolean {
+  try {
+    return new URL(callbackUrl).pathname === pathname;
+  } catch {
+    return callbackUrl.endsWith(pathname);
+  }
+}
+
+function isWhatsAppCallback(callbackUrl: string): boolean {
+  return matchesPathname(callbackUrl, "/deliver/whatsapp");
+}
+
+function isTelegramCallback(callbackUrl: string): boolean {
+  return matchesPathname(callbackUrl, "/deliver/telegram");
+}
+
+function isSlackCallback(callbackUrl: string): boolean {
+  try {
+    return new URL(callbackUrl).pathname === "/deliver/slack";
+  } catch {
+    return callbackUrl.endsWith("/deliver/slack");
+  }
+}
+
+function parseSlackCallbackParams(callbackUrl: string): {
+  channel?: string;
+  threadTs?: string;
+  messageTs?: string;
+} {
+  try {
+    const url = new URL(callbackUrl);
+    return {
+      channel: url.searchParams.get("channel") ?? undefined,
+      threadTs: url.searchParams.get("threadTs") ?? undefined,
+      messageTs: url.searchParams.get("messageTs") ?? undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Per-channel direct delivery
+// ---------------------------------------------------------------------------
+
+async function deliverWhatsApp(
+  payload: ChannelReplyPayload,
+): Promise<ChannelDeliveryResult> {
+  const { chatId, text, attachments, approval } = payload;
+
+  if (text) {
+    await sendWhatsAppReply(chatId, text, approval);
+  } else if (approval) {
+    await sendWhatsAppReply(
+      chatId,
+      approval.plainTextFallback || "Approval required",
+      approval,
+    );
+  }
+
+  if (attachments && attachments.length > 0) {
+    const result = await sendWhatsAppAttachments(chatId, attachments);
+    if (result.allFailed && !text) {
+      throw new ChannelDeliveryError(
+        502,
+        `All ${result.failureCount} attachments failed to deliver`,
+      );
+    }
+  }
+
+  log.info({ chatId, hasText: !!text }, "WhatsApp reply delivered (direct)");
+  return { ok: true };
+}
+
+async function deliverTelegram(
+  payload: ChannelReplyPayload,
+): Promise<ChannelDeliveryResult> {
+  const { chatId, text, attachments, approval, chatAction } = payload;
+
+  if (chatAction === "typing") {
+    await sendTelegramTypingIndicator(chatId);
+    log.debug({ chatId }, "Telegram typing indicator delivered (direct)");
+    return { ok: true };
+  }
+
+  if (text) {
+    await sendTelegramReply(chatId, text, approval);
+  } else if (approval) {
+    await sendTelegramReply(
+      chatId,
+      approval.plainTextFallback || "Approval required",
+      approval,
+    );
+  }
+
+  if (attachments && attachments.length > 0) {
+    const result = await sendTelegramAttachments(chatId, attachments);
+    if (result.allFailed && !text) {
+      throw new ChannelDeliveryError(
+        502,
+        `All ${result.failureCount} attachments failed to deliver`,
+      );
+    }
+  }
+
+  log.info({ chatId, hasText: !!text }, "Telegram reply delivered (direct)");
+  return { ok: true };
+}
+
+async function deliverSlack(
+  callbackUrl: string,
+  payload: ChannelReplyPayload,
+): Promise<ChannelDeliveryResult> {
+  const { chatId, text, attachments, chatAction, blocks } = payload;
+  const params = parseSlackCallbackParams(callbackUrl);
+  const threadTs = params.threadTs;
+
+  // Emoji reaction
+  if (payload.reaction) {
+    await sendSlackReaction(
+      chatId,
+      payload.reaction.name,
+      payload.reaction.messageTs,
+      payload.reaction.action,
+    );
+    return { ok: true };
+  }
+
+  // Assistants API thread status
+  if (payload.assistantThreadStatus) {
+    const {
+      channel,
+      threadTs: statusThreadTs,
+      status,
+    } = payload.assistantThreadStatus;
+    await sendSlackAssistantThreadStatus(channel, statusThreadTs, status);
+    return { ok: true };
+  }
+
+  // Typing indicator
+  if (chatAction === "typing") {
+    const placeholderTs = await sendSlackTypingIndicator(chatId, threadTs);
+    log.debug({ chatId }, "Slack typing indicator delivered (direct)");
+    return { ok: true, ts: placeholderTs };
+  }
+
+  // Text + blocks delivery
+  let sentTs: string | undefined;
+  if (text) {
+    const result = await sendSlackReply(chatId, text, {
+      threadTs,
+      blocks: blocks as unknown[] | undefined,
+      approval: payload.approval,
+      useBlocks: payload.useBlocks,
+      ephemeral: payload.ephemeral,
+      user: payload.user,
+      messageTs: payload.messageTs,
+    });
+    sentTs = result.ts;
+  } else if (payload.approval) {
+    const result = await sendSlackReply(
+      chatId,
+      payload.approval.plainTextFallback || "Approval required",
+      {
+        threadTs,
+        approval: payload.approval,
+      },
+    );
+    sentTs = result.ts;
+  }
+
+  // Attachments
+  if (attachments && attachments.length > 0) {
+    const result = await sendSlackAttachments(chatId, attachments, threadTs);
+    if (result.allFailed && !text) {
+      throw new ChannelDeliveryError(
+        502,
+        `All ${result.failureCount} attachments failed to deliver`,
+      );
+    }
+  }
+
+  log.info({ chatId, hasText: !!text }, "Slack reply delivered (direct)");
+  return { ok: true, ts: sentTs };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true when the given callback URL targets a channel whose
+ * outbound delivery is handled directly by the assistant (no gateway hop).
+ */
+export function isDirectDelivery(callbackUrl: string): boolean {
+  return (
+    isWhatsAppCallback(callbackUrl) ||
+    isTelegramCallback(callbackUrl) ||
+    isSlackCallback(callbackUrl)
+  );
+}
+
+/**
+ * Deliver a channel reply directly to the provider API, bypassing the
+ * gateway HTTP proxy.  Callers MUST check `isDirectDelivery()` first.
+ */
+export async function deliverDirect(
+  callbackUrl: string,
+  payload: ChannelReplyPayload,
+): Promise<ChannelDeliveryResult> {
+  if (isWhatsAppCallback(callbackUrl)) {
+    return deliverWhatsApp(payload);
+  }
+  if (isTelegramCallback(callbackUrl)) {
+    return deliverTelegram(payload);
+  }
+  if (isSlackCallback(callbackUrl)) {
+    return deliverSlack(callbackUrl, payload);
+  }
+
+  // Defensive — isDirectDelivery should have returned false.
+  throw new Error(
+    `deliverDirect called for unsupported callback: ${callbackUrl}`,
+  );
+}