@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091926.ebb2d62

package/src/memory/v3/tree.ts

@@ -1,174 +0,0 @@
-import { existsSync } from "node:fs";
-import { readdir, readFile } from "node:fs/promises";
-import { dirname, join, relative, sep } from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { parse as parseYaml } from "yaml";
-
-import { getWorkspaceDir } from "../../util/platform.js";
-import type {
-  LeafFrontmatter,
-  LeafNode,
-  LeafPath,
-  LeafTree,
-  Slug,
-} from "./types.js";
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-
-/** Bundled stub data shipped alongside the loader. */
-const BUNDLED_DATA_DIR = join(HERE, "data");
-
-/**
- * Resolve the directory the loaders should read leaf-tree artifacts from.
- *
- * Prefers a maintainer's per-instance workspace override
- * (`<workspace>/memory/v3/data/`) when present, otherwise falls back to the
- * generic bundled stub shipped in this package.
- *
- * The public {@link loadLeafTree} API still takes an explicit `dataDir` for
- * testability; orchestrators that want the runtime default call this helper.
- */
-export function resolveDataDir(): string {
-  const workspaceData = join(getWorkspaceDir(), "memory", "v3", "data");
-  if (existsSync(workspaceData)) return workspaceData;
-  return BUNDLED_DATA_DIR;
-}
-
-/** Recursively collect every `*.md` file under `dir`. */
-async function collectMarkdownFiles(dir: string): Promise<string[]> {
-  const entries = await readdir(dir, { withFileTypes: true });
-  const files: string[] = [];
-  for (const entry of entries) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...(await collectMarkdownFiles(full)));
-    } else if (entry.isFile() && entry.name.endsWith(".md")) {
-      files.push(full);
-    }
-  }
-  return files;
-}
-
-/**
- * Split a leaf `.md` file into its YAML frontmatter and body.
- *
- * Frontmatter is the `---`-delimited block at the top of the file; everything
- * after the closing delimiter is the description body.
- */
-function splitFrontmatter(raw: string): { frontmatter: string; body: string } {
-  const normalized = raw.replace(/^/, "");
-  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(normalized);
-  if (!match) {
-    throw new Error("leaf markdown is missing YAML frontmatter");
-  }
-  return { frontmatter: match[1], body: match[2] };
-}
-
-function parseLeafFrontmatter(yaml: string, file: string): LeafFrontmatter {
-  const parsed = parseYaml(yaml) as unknown;
-  if (parsed === null || typeof parsed !== "object") {
-    throw new Error(`leaf ${file} frontmatter is not a mapping`);
-  }
-  const record = parsed as Record<string, unknown>;
-  if (typeof record.path !== "string") {
-    throw new Error(`leaf ${file} frontmatter is missing a string \`path\``);
-  }
-  if (typeof record.in_core !== "boolean") {
-    throw new Error(
-      `leaf ${file} frontmatter is missing a boolean \`in_core\``,
-    );
-  }
-  return {
-    path: record.path,
-    in_core: record.in_core,
-    ...(typeof record.id === "string" ? { id: record.id } : {}),
-  };
-}
-
-/** Derive the canonical leaf path from a file's location under `leaves/`. */
-function pathFromLocation(leavesDir: string, file: string): LeafPath {
-  return relative(leavesDir, file).replace(/\.md$/, "").split(sep).join("/");
-}
-
-/**
- * Load the leaf tree from `dataDir`. READ-ONLY: walks `leaves/**\/*.md` and
- * reads `assignments.json` without mutating anything on disk.
- *
- * Builds:
- * - `leaves`: leaf path → {@link LeafNode} (frontmatter, description, domain,
- *   and the slugs assigned to it).
- * - `byPage`: slug → the leaf paths it is assigned to (inverted assignments).
- *
- * Page→leaf membership precedence is per-page: when `pageLeaves` supplies a
- * non-empty array for a slug, those frontmatter-derived leaves win for that
- * page; slugs absent from `pageLeaves` (or mapped to an empty array) fall back
- * to `assignments.json`. Omitting `pageLeaves` reproduces the legacy
- * assignments.json-only behavior exactly (used by the bundled stub and tests);
- * orchestrators supply `pageLeaves` from the page index.
- */
-export async function loadLeafTree(
-  dataDir: string,
-  pageLeaves?: Map<Slug, LeafPath[]>,
-): Promise<LeafTree> {
-  const leavesDir = join(dataDir, "leaves");
-  const files = await collectMarkdownFiles(leavesDir);
-
-  const nodes = await Promise.all(
-    files.map(async (file): Promise<LeafNode> => {
-      const raw = await readFile(file, "utf8");
-      const { frontmatter, body } = splitFrontmatter(raw);
-      const path = pathFromLocation(leavesDir, file);
-      return {
-        path,
-        frontmatter: parseLeafFrontmatter(frontmatter, file),
-        description: body.trim(),
-        members: [],
-        domain: path.split("/")[0],
-      };
-    }),
-  );
-
-  const leaves = new Map<LeafPath, LeafNode>(
-    nodes.map((node) => [node.path, node]),
-  );
-
-  const assignmentsRaw = await readFile(
-    join(dataDir, "assignments.json"),
-    "utf8",
-  );
-  const assignments = JSON.parse(assignmentsRaw) as Record<Slug, LeafPath[]>;
-
-  const slugs = new Set<Slug>(Object.keys(assignments));
-  if (pageLeaves) for (const slug of pageLeaves.keys()) slugs.add(slug);
-
-  const byPage = new Map<Slug, LeafPath[]>();
-  for (const slug of slugs) {
-    const fromFrontmatter = pageLeaves?.get(slug);
-    const leafPaths =
-      fromFrontmatter && fromFrontmatter.length > 0
-        ? fromFrontmatter
-        : (assignments[slug] ?? []);
-    byPage.set(slug, [...leafPaths]);
-    for (const leafPath of leafPaths) {
-      leaves.get(leafPath)?.members.push(slug);
-    }
-  }
-
-  return { leaves, byPage };
-}
-
-/** The slugs assigned to a leaf. */
-export function membersOf(tree: LeafTree, leaf: LeafPath): Slug[] {
-  return tree.leaves.get(leaf)?.members ?? [];
-}
-
-/** The leaf paths a slug is assigned to. */
-export function leavesOf(tree: LeafTree, slug: Slug): LeafPath[] {
-  return tree.byPage.get(slug) ?? [];
-}
-
-/** The unique slugs owned by every leaf in `core` (expand leaf-paths → slugs). */
-export function coreSlugs(tree: LeafTree, core: Set<LeafPath>): Set<Slug> {
-  return new Set([...core].flatMap((leaf) => membersOf(tree, leaf)));
-}

package/src/memory/v3/types.ts

@@ -1,59 +0,0 @@
-export type LeafPath = string; // dot- or slash-pathed taxonomy node
-export type Slug = string;
-
-/**
- * Injection-block id for the v3 live `<memory>` block. Shared between the
- * producer (the v3 injector in `shadow-plugin.ts`) and the v2-suppression
- * consumer (`conversation-runtime-assembly.ts`), which keys off this id to
- * detect that v3 actually produced a block this turn. Keeping it in one place
- * makes a rename a compile error on both sides instead of a silent
- * suppression bypass.
- */
-export const MEMORY_V3_BLOCK_ID = "memory-v3" as const;
-
-export interface LeafFrontmatter {
-  path: LeafPath;
-  in_core: boolean;
-  /**
-   * Optional stable identifier for the leaf, independent of its taxonomy path.
-   * Older leaves predate this field and omit it, so it is optional.
-   */
-  id?: string;
-}
-
-export interface LeafNode {
-  path: LeafPath;
-  frontmatter: LeafFrontmatter;
-  description: string;
-  members: Slug[];
-  domain: string;
-}
-
-export interface LeafTree {
-  leaves: Map<LeafPath, LeafNode>;
-  byPage: Map<Slug, LeafPath[]>;
-}
-
-export interface WorkingSetEntry {
-  slug: Slug;
-  selectedAtTurn: number;
-  pinned: boolean;
-  lastSeenTurn: number;
-}
-
-export interface TurnContext {
-  conversationId: string;
-  turnNumber: number;
-  currentMessage: string;
-  recentContext: string;
-  /**
-   * Optional situational signal — the current date plus the live NOW.md
-   * scratchpad — so a leaf or page can be routed/selected on a date or
-   * live-state cue the message itself never names (e.g. a person whose
-   * anniversary is today). Omitted when unavailable; the router and selector
-   * render nothing for an undefined value.
-   */
-  situationalContext?: string;
-}
-
-export type SelectionSource = "l1+l2" | "core+l2" | "needle" | "carry-forward";

package/src/notifications/__tests__/emit-signal-home-feed.test.ts

@@ -1,187 +0,0 @@
-/**
- * Verifies that `emitNotificationSignal` invokes the home-feed side
- * effect after dispatching, and that the side effect's background-only
- * filter correctly suppresses interactive signals.
- *
- * The side effect itself is unit-tested in `home-feed-side-effect.test.ts`;
- * this test exercises the wire-up boundary in `emit-signal.ts` by mocking
- * at the `appendFeedItem` / `getConversation` boundary so the real
- * background-filter logic runs end-to-end.
- */
-import { beforeEach, describe, expect, mock, test } from "bun:test";
-
-import type { FeedItem } from "../../home/feed-types.js";
-import type {
-  NotificationDecision,
-  NotificationDeliveryResult,
-} from "../types.js";
-
-// ── Module mocks ───────────────────────────────────────────────────────
-//
-// `mock.module` is hoisted, so these intercepts apply before the module
-// under test resolves its imports. Closures over module-scoped state
-// let each test reset and inspect captured calls afterwards.
-
-const appendCalls: FeedItem[] = [];
-let conversationRow: { conversationType: string } | null = null;
-
-mock.module("../../home/feed-writer.js", () => ({
-  appendFeedItem: async (item: FeedItem) => {
-    appendCalls.push(item);
-  },
-}));
-
-// home-feed-side-effect.ts only consumes `getConversation`.
-mock.module("../../memory/conversation-crud.js", () => ({
-  getConversation: () => conversationRow,
-  reserveMessage: mock(async () => ({ id: "msg-reserve" })),
-}));
-
-// Stub the broadcaster so emit-signal's `getBroadcaster()` does not need
-// to build real adapters or pull in `conversation-pairing.ts` transitively
-// (which would force us to mirror the full `conversation-crud.js` surface).
-class StubBroadcaster {
-  setOnConversationCreated() {}
-  async broadcastDecision() {
-    return [];
-  }
-}
-mock.module("../broadcaster.js", () => ({
-  NotificationBroadcaster: StubBroadcaster,
-}));
-
-mock.module("../adapters/macos.js", () => ({
-  VellumAdapter: class {},
-  isGuardianSensitiveEvent: () => false,
-}));
-mock.module("../adapters/slack.js", () => ({
-  SlackAdapter: class {},
-}));
-mock.module("../adapters/telegram.js", () => ({
-  TelegramAdapter: class {},
-}));
-
-// Stub out the persistence + channel resolution layers so emitNotificationSignal
-// can run end-to-end without touching the DB / contacts store / LLM.
-
-mock.module("../events-store.js", () => ({
-  createEvent: (params: { id: string }) => ({
-    id: params.id,
-    sourceEventName: "schedule.notify",
-    sourceChannel: "scheduler",
-    sourceContextId: "conv-source-1",
-    attentionHintsJson: "{}",
-    payloadJson: "{}",
-    dedupeKey: null,
-    createdAt: 0,
-    updatedAt: 0,
-  }),
-  updateEventDedupeKey: () => {},
-}));
-
-mock.module("../decisions-store.js", () => ({
-  updateDecision: () => {},
-}));
-
-mock.module("../../contacts/contact-store.js", () => ({
-  findGuardianForChannel: () => null,
-  listGuardianChannels: () => [],
-}));
-
-const stubDecision: NotificationDecision = {
-  shouldNotify: true,
-  selectedChannels: ["vellum"],
-  reasoningSummary: "test",
-  renderedCopy: {
-    vellum: { title: "Background job done", body: "Summary of what happened." },
-  },
-  dedupeKey: "dk-1",
-  confidence: 1,
-  fallbackUsed: false,
-};
-
-mock.module("../decision-engine.js", () => ({
-  evaluateSignal: async () => stubDecision,
-  // Pass the decision through unchanged — emit-signal calls this after
-  // evaluateSignal and only re-persists when the reference changes.
-  enforceRoutingIntent: (decision: NotificationDecision) => decision,
-}));
-
-mock.module("../deterministic-checks.js", () => ({
-  runDeterministicChecks: async () => ({ passed: true }),
-}));
-
-const stubDeliveryResults: NotificationDeliveryResult[] = [
-  {
-    channel: "vellum",
-    destination: "vellum-client",
-    status: "sent",
-    conversationId: "conv-vellum-1",
-  },
-];
-
-mock.module("../runtime-dispatch.js", () => ({
-  dispatchDecision: async () => ({
-    dispatched: true,
-    reason: "Dispatched to 1/1 channels",
-    deliveryResults: stubDeliveryResults,
-  }),
-}));
-
-const { emitNotificationSignal } = await import("../emit-signal.js");
-
-// ── Tests ──────────────────────────────────────────────────────────────
-
-beforeEach(() => {
-  appendCalls.length = 0;
-  conversationRow = null;
-});
-
-describe("emitNotificationSignal home-feed wire-up", () => {
-  test("background-conversation signal triggers appendFeedItem", async () => {
-    conversationRow = { conversationType: "background" };
-
-    const result = await emitNotificationSignal({
-      sourceEventName: "schedule.notify",
-      sourceChannel: "scheduler",
-      sourceContextId: "conv-source-1",
-      contextPayload: { title: "Background job done" },
-      attentionHints: {
-        requiresAction: false,
-        urgency: "medium",
-        isAsyncBackground: false,
-        visibleInSourceNow: false,
-      },
-    });
-
-    expect(result.dispatched).toBe(true);
-    expect(appendCalls).toHaveLength(1);
-    const appended = appendCalls[0]!;
-    expect(appended.id).toBe(`notif:${result.signalId}`);
-    expect(appended.title).toBe("Background job done");
-    expect(appended.summary).toBe("Summary of what happened.");
-    // The feed item's conversationId points to the source conversation
-    // that emitted the signal, not the conversation the notification
-    // pipeline spawned to handle it.
-    expect(appended.conversationId).toBe("conv-source-1");
-  });
-
-  test("interactive standard conversation does NOT trigger appendFeedItem", async () => {
-    conversationRow = { conversationType: "standard" };
-
-    const result = await emitNotificationSignal({
-      sourceEventName: "schedule.notify",
-      sourceChannel: "scheduler",
-      sourceContextId: "conv-source-1",
-      attentionHints: {
-        requiresAction: false,
-        urgency: "medium",
-        isAsyncBackground: false,
-        visibleInSourceNow: true,
-      },
-    });
-
-    expect(result.dispatched).toBe(true);
-    expect(appendCalls).toHaveLength(0);
-  });
-});

package/src/plugins/defaults/circuit-breaker/middlewares/circuitBreaker.ts

@@ -1,93 +0,0 @@
-import type {
-  CircuitBreakerArgs,
-  CircuitBreakerResult,
-  Middleware,
-} from "../../../types.js";
-
-/**
- * Consecutive failures required to trip the breaker. Matches the legacy
- * `COMPACTION_CIRCUIT_FAILURE_THRESHOLD` in `conversation-agent-loop.ts`.
- */
-export const COMPACTION_CIRCUIT_FAILURE_THRESHOLD = 3;
-
-/**
- * Cooldown window after the breaker trips, during which auto-compaction is
- * suspended. Matches the legacy `COMPACTION_CIRCUIT_COOLDOWN_MS`.
- */
-export const COMPACTION_CIRCUIT_COOLDOWN_MS = 60 * 60 * 1000;
-
-/**
- * Default middleware for the `circuitBreaker` pipeline. A thin wrapper over the
- * state container passed in `CircuitBreakerArgs.state`:
- *
- * - `{ key }` — query. Defers to `next` for the current
- *   `{ open, cooldownRemainingMs? }`.
- * - `{ key, outcome }` — update state based on outcome, then defer to `next`
- *   for the post-update decision. A run of three failures trips the breaker;
- *   any non-failure outcome resets both the counter and the cooldown timestamp.
- *
- * Event emission preserves the existing `trackCompactionOutcome` behavior:
- * `compaction_circuit_open` fires once when the counter first reaches the
- * threshold while the circuit is dormant; `compaction_circuit_closed` fires
- * only on the open→closed transition.
- */
-const circuitBreaker: Middleware<CircuitBreakerArgs, CircuitBreakerResult> =
-  async function circuitBreaker(args, next) {
-    const { outcome, state, onEvent } = args;
-
-    // Update branch — mutate state first, then defer to the downstream
-    // chain (or terminal) for the decision so outer observers still see
-    // the fully-processed outcome. Separating state mutation from
-    // decision computation also keeps this middleware composable: an
-    // outer plugin may wrap the invocation to observe both the pre-update
-    // args and the post-update result.
-    if (outcome !== undefined) {
-      if (outcome === "failure") {
-        state.consecutiveCompactionFailures += 1;
-        // Treat a stale/expired open-until timestamp the same as null so
-        // a new 3-strike window can re-open the circuit after the prior
-        // cooldown elapses. Without this, subsequent trips would no-op
-        // because `compactionCircuitOpenUntil` remains set to a past
-        // timestamp even though the breaker is effectively closed.
-        const circuitDormant =
-          state.compactionCircuitOpenUntil === null ||
-          Date.now() >= state.compactionCircuitOpenUntil;
-        if (
-          state.consecutiveCompactionFailures >=
-            COMPACTION_CIRCUIT_FAILURE_THRESHOLD &&
-          circuitDormant
-        ) {
-          const openUntil = Date.now() + COMPACTION_CIRCUIT_COOLDOWN_MS;
-          state.compactionCircuitOpenUntil = openUntil;
-          if (onEvent) {
-            onEvent({
-              type: "compaction_circuit_open",
-              conversationId: state.conversationId,
-              reason: "3_consecutive_failures",
-              openUntil,
-            });
-          }
-        }
-      } else {
-        // Emit only on the open→closed transition; firing on the common
-        // closed→closed case would be noise.
-        const wasOpen = state.compactionCircuitOpenUntil !== null;
-        state.consecutiveCompactionFailures = 0;
-        state.compactionCircuitOpenUntil = null;
-        if (wasOpen && onEvent) {
-          onEvent({
-            type: "compaction_circuit_closed",
-            conversationId: state.conversationId,
-          });
-        }
-      }
-    }
-
-    // Defer to downstream (the terminal, in the default registration, but
-    // potentially another plugin in a customized chain) for the final
-    // decision. The terminal's implementation is the canonical read of
-    // the (now-updated) state container.
-    return next(args);
-  };
-
-export default circuitBreaker;

package/src/plugins/defaults/circuit-breaker/package.json

@@ -1,15 +0,0 @@
-{
-  "name": "default-circuit-breaker",
-  "version": "1.0.0",
-  "description": "First-party default plugin wrapping the assistant's built-in circuit-breaker pipeline with a passthrough implementation.",
-  "private": true,
-  "license": "MIT",
-  "type": "module",
-  "main": "./register.ts",
-  "engines": {
-    "node": ">=20.12.0"
-  },
-  "peerDependencies": {
-    "@vellumai/plugin-api": "^0.8.0"
-  }
-}

package/src/plugins/defaults/circuit-breaker/register.ts

@@ -1,39 +0,0 @@
-/**
- * Default `circuitBreaker` plugin.
- *
- * Replicates the inline compaction circuit-breaker logic that previously
- * lived in `daemon/conversation-agent-loop.ts`: three consecutive summary-LLM
- * failures open the circuit for a one-hour cooldown, and any successful
- * compaction resets the counter.
- *
- * The plugin is a thin wrapper over the state container passed in
- * `CircuitBreakerArgs.state`. The {@link Conversation} owns the underlying
- * fields (`consecutiveCompactionFailures`, `compactionCircuitOpenUntil`)
- * because dev-only playground routes (`POST /playground/reset-compaction-circuit`,
- * `POST /playground/inject-compaction-failures`) read and mutate them
- * directly. Keeping ownership on the conversation lets this plugin stay a
- * pure wrapper while preserving those hatches.
- *
- * The `key` parameter is carried through for multi-circuit futures but the
- * default plugin currently bundles all circuit state into the `state`
- * container; the key is attached to the log record via the pipeline runner.
- */
-
-import { type Plugin } from "../../types.js";
-import circuitBreaker from "./middlewares/circuitBreaker.js";
-import pkg from "./package.json" with { type: "json" };
-
-/**
- * Default plugin registered at daemon startup. Consumers negotiate against
- * `circuitBreakerApi@v1` via the registry's capability table.
- */
-export const defaultCircuitBreakerPlugin: Plugin = {
-  manifest: {
-    name: pkg.name,
-    version: pkg.version,
-  },
-
-  middleware: {
-    circuitBreaker,
-  },
-};

package/src/plugins/defaults/compaction/middlewares/compaction.ts

@@ -1,25 +0,0 @@
-import type {
-  CompactionArgs,
-  CompactionResult,
-  Middleware,
-} from "../../../types.js";
-
-/**
- * Passthrough middleware for the `compaction` pipeline. Forwards to
- * `next(args)` so any custom plugins layered outside still run; when this is
- * the only middleware, `next` is the terminal handler (`../terminal.ts`) and
- * returns the real compaction output.
- *
- * Defaults register at the OUTERMOST onion position, so deciding here without
- * calling `next` would shadow every later-registered plugin. Routing through
- * `next(args)` lets user middleware participate normally.
- */
-const defaultCompactionMiddleware: Middleware<
-  CompactionArgs,
-  CompactionResult
-> = async function defaultCompaction(args, next, ctx) {
-  void ctx;
-  return next(args);
-};
-
-export default defaultCompactionMiddleware;

package/src/plugins/defaults/compaction/register.ts

@@ -1,35 +0,0 @@
-/**
- * Default `compaction` plugin.
- *
- * The plugin's middleware is a passthrough — it calls `next(args)` and returns
- * the result unchanged. The actual compaction lives in the terminal handler in
- * `./terminal.ts`, which is wired in as the pipeline's `terminal` argument by
- * the `runPipeline` call site in `daemon/conversation-agent-loop.ts`. This
- * separation matters: the default plugin is registered before any user plugin
- * (defaults load first in `bootstrapPlugins()`), which puts it at the
- * OUTERMOST position of the onion chain. If the default middleware were to
- * invoke the terminal directly without calling `next`, it would shadow every
- * later-registered plugin. Routing through `next(args)` lets user middleware
- * participate normally.
- *
- * Design doc: `.private/plans/agent-plugin-system.md` (PR 25).
- */
-
-import { type Plugin } from "../../types.js";
-import defaultCompactionMiddleware from "./middlewares/compaction.js";
-import pkg from "./package.json" with { type: "json" };
-
-/**
- * Manifest + middleware wiring for the default compaction plugin. The
- * registration happens in `daemon/external-plugins-bootstrap.ts` before
- * {@link bootstrapPlugins} fires plugin `init()` hooks.
- */
-export const defaultCompactionPlugin: Plugin = {
-  manifest: {
-    name: pkg.name,
-    version: pkg.version,
-  },
-  middleware: {
-    compaction: defaultCompactionMiddleware,
-  },
-};