@vellumai/assistant 0.10.2-dev.202606250318.5e7cfb0 → 0.10.2

package/src/agent/loop-exclusive-tool.test.ts

@@ -1,150 +0,0 @@
-/**
- * Verifies the agent loop's exclusive-tool dispatch: when a tool the loop is
- * told is exclusive (e.g. the advisor) appears in a multi-call turn, only that
- * tool runs and the siblings are deferred un-run with a benign result — so the
- * model incorporates the exclusive tool's output before acting on anything
- * else. Drives the REAL loop, mocking only the provider boundary.
- */
-import { describe, expect, test } from "bun:test";
-
-import { createMockProvider } from "../__tests__/helpers/mock-provider.js";
-import type { ContentBlock, ProviderResponse } from "../providers/types.js";
-import { AgentLoop } from "./loop.js";
-
-const endTurn = (text: string): ProviderResponse => ({
-  content: [{ type: "text", text }],
-  model: "mock-model",
-  usage: { inputTokens: 1, outputTokens: 1 },
-  stopReason: "end_turn",
-});
-
-const toolUseTurn = (
-  blocks: Array<{ id: string; name: string }>,
-): ProviderResponse => ({
-  content: [
-    { type: "text", text: "working" },
-    ...blocks.map((b) => ({
-      type: "tool_use" as const,
-      id: b.id,
-      name: b.name,
-      input: {},
-    })),
-  ],
-  model: "mock-model",
-  usage: { inputTokens: 1, outputTokens: 1 },
-  stopReason: "tool_use",
-});
-
-function toolResults(history: { content: ContentBlock[] }[]) {
-  return history
-    .flatMap((m) => m.content)
-    .filter(
-      (b): b is Extract<ContentBlock, { type: "tool_result" }> =>
-        b.type === "tool_result",
-    );
-}
-
-const baseRun = {
-  requestId: "req-excl",
-  onEvent: () => {},
-  callSite: "mainAgent" as const,
-  trust: { sourceChannel: "vellum" as const, trustClass: "unknown" as const },
-};
-
-describe("AgentLoop — exclusive tool deferral", () => {
-  test("runs the exclusive tool alone and defers sibling calls un-run", async () => {
-    const { provider } = createMockProvider([
-      toolUseTurn([
-        { id: "call-advisor", name: "advisor" },
-        { id: "call-edit", name: "write_file" },
-      ]),
-      endTurn("done"),
-    ]);
-
-    const executed: string[] = [];
-    const loop = new AgentLoop({
-      provider,
-      systemPrompt: "sys",
-      conversationId: "excl-1",
-      tools: [
-        { name: "advisor", description: "", input_schema: { type: "object" } },
-        {
-          name: "write_file",
-          description: "",
-          input_schema: { type: "object" },
-        },
-      ],
-      toolExecutor: async (name) => {
-        executed.push(name);
-        return { content: `ran ${name}`, isError: false };
-      },
-      isExclusiveTool: (name) => name === "advisor",
-    });
-
-    const { history } = await loop.run({
-      ...baseRun,
-      messages: [{ role: "user", content: [{ type: "text", text: "do it" }] }],
-    });
-
-    // Only the exclusive tool actually executed.
-    expect(executed).toEqual(["advisor"]);
-
-    const results = toolResults(history);
-    const advisorResult = results.find(
-      (b) => b.tool_use_id === "call-advisor",
-    )!;
-    const editResult = results.find((b) => b.tool_use_id === "call-edit")!;
-
-    // The advisor ran; the sibling came back un-run (not an error) so the model
-    // can re-issue it after reading the guidance.
-    expect(advisorResult.content).toBe("ran advisor");
-    expect(editResult.content).toContain("not run");
-    expect(editResult.content).toContain("advisor");
-    expect(editResult.is_error).toBe(false);
-  });
-
-  test("runs sibling tools normally when no exclusive tool is present", async () => {
-    const { provider } = createMockProvider([
-      toolUseTurn([
-        { id: "call-read", name: "read_file" },
-        { id: "call-write", name: "write_file" },
-      ]),
-      endTurn("done"),
-    ]);
-
-    const executed: string[] = [];
-    const loop = new AgentLoop({
-      provider,
-      systemPrompt: "sys",
-      conversationId: "excl-2",
-      tools: [
-        {
-          name: "read_file",
-          description: "",
-          input_schema: { type: "object" },
-        },
-        {
-          name: "write_file",
-          description: "",
-          input_schema: { type: "object" },
-        },
-      ],
-      toolExecutor: async (name) => {
-        executed.push(name);
-        return { content: `ran ${name}`, isError: false };
-      },
-      isExclusiveTool: (name) => name === "advisor",
-    });
-
-    const { history } = await loop.run({
-      ...baseRun,
-      messages: [{ role: "user", content: [{ type: "text", text: "do it" }] }],
-    });
-
-    // Both non-exclusive tools ran; nothing was deferred.
-    expect(executed.sort()).toEqual(["read_file", "write_file"]);
-    for (const result of toolResults(history)) {
-      expect(result.content).not.toContain("not run");
-    }
-  });
-});

package/src/api/constants/sse-replay.ts

@@ -1,41 +0,0 @@
-/**
- * Maximum number of events the daemon's per-process SSE replay ring
- * retains for `Last-Event-ID` resume. This is the ring's count bound; the
- * ring is also bounded by total bytes and entry age (whichever limit is
- * hit first wins), so the live ring can hold *fewer* than this many
- * events, never more. The daemon-side definition and eviction live in
- * `assistant/src/runtime/assistant-stream-state.ts`.
- *
- * Exposed on the API surface so the web client's SSE consumer can size
- * its seq-gap tolerance against the same number the daemon buffers
- * against, instead of hard-coding a duplicate.
- *
- * A live seq gap smaller than this is benign: the global per-assistant
- * `seq` counter is stamped before fanout, but the hub deliberately
- * withholds some events from a given subscriber — self-echo-suppressed
- * `sync_changed` (a client's own mutation echo) and capability-targeted
- * host-proxy events — so a subscriber legitimately sees its cursor skip a
- * few seqs it was never going to receive. Such a hole is not data loss
- * and must not trigger a destructive authoritative snapshot heal. Only a
- * gap that meets or exceeds this count proves the live suffix fell
- * outside the ring entirely and is genuinely non-contiguous.
- */
-export const SSE_REPLAY_RING_COUNT_LIMIT = 200;
-
-/**
- * Maximum age (in milliseconds) an event may reach in the daemon's SSE
- * replay ring before it is evicted, regardless of count or byte usage.
- * The daemon-side definition and eviction live in
- * `assistant/src/runtime/assistant-stream-state.ts`.
- *
- * Exposed alongside the count bound so the web client can reason about
- * the age dimension of the ring too. A small live seq gap is only safe to
- * treat as benign when the client has been continuously receiving events
- * — live delivery is concurrent with stamping, so a connected subscriber
- * never relies on the ring. Once the connection has been quiet for longer
- * than this window (a disconnect/resume), events the client missed may
- * have aged out of the ring and become unrecoverable by replay, so even a
- * small seq gap must trigger an authoritative reconcile rather than be
- * waved through.
- */
-export const SSE_REPLAY_RING_AGE_LIMIT_MS = 30_000;

package/src/api/events/conversation-notice.ts

@@ -1,26 +0,0 @@
-/**
- * `conversation_notice` SSE event.
- *
- * Non-terminal, conversation-scoped notice for actionable runtime conditions
- * that should not mark the turn as failed. The client may render CTA UI from
- * this event while preserving the current assistant response.
- */
-
-import { z } from "zod";
-
-import { ConversationErrorCodeSchema } from "./conversation-error.js";
-
-export const ConversationNoticeSourceSchema = z.enum(["memory_v3"]);
-
-export const ConversationNoticeEventSchema = z.object({
-  type: z.literal("conversation_notice"),
-  conversationId: z.string(),
-  source: ConversationNoticeSourceSchema,
-  code: ConversationErrorCodeSchema,
-  userMessage: z.string(),
-  errorCategory: z.string().optional(),
-});
-
-export type ConversationNoticeEvent = z.infer<
-  typeof ConversationNoticeEventSchema
->;

package/src/approvals/guardian-channel-delivery.ts

@@ -1,30 +0,0 @@
-/**
- * Shared addressing helpers for guardian requester-facing channel notices.
- *
- * Requester notices (approval, denial, expiry) are delivered straight to the
- * requester's chat via `deliverChannelReply` — independent of the
- * guardian-facing notification pipeline. Centralizing the addressing rules here
- * keeps the decision resolvers and the timer-driven expiry sweep from drifting
- * apart on how a requester is reached.
- */
-
-/**
- * Resolve the callback-less delivery route for a channel (e.g. `/deliver/slack`).
- *
- * Used when there is no inbound reply callback URL to post back to — the
- * guardian decided off-channel (desktop), or the expiry sweep fired on a timer
- * with no originating request in hand. Returns null for channels that have no
- * deliverable route (e.g. email, the in-app vellum surface).
- */
-export function resolveDeliverCallbackUrlForChannel(
-  channel: string,
-): string | null {
-  switch (channel) {
-    case "telegram":
-    case "whatsapp":
-    case "slack":
-      return `/deliver/${channel}`;
-    default:
-      return null;
-  }
-}

package/src/approvals/guardian-expiry-notifier.ts

@@ -1,148 +0,0 @@
-/**
- * Expiry side effects for canonical guardian requests.
- *
- * When the canonical expiry sweep transitions a pending request to `expired`,
- * the request's cards are withdrawn — but nobody is told and any in-memory
- * interaction is left dangling. This module fills that gap:
- *
- *  - the requester is told their request expired (for the persistent,
- *    requester-facing kinds: `access_request`, `tool_grant_request`), and
- *  - the in-memory pending interaction is released (for the interaction-bound
- *    `tool_approval` kind).
- *
- * Delivery goes straight to the requester via `deliverChannelReply` on the
- * callback-less `/deliver/<channel>` route — NOT the notification pipeline,
- * which is guardian-facing (`emitNotificationSignal` resolves the *guardian's*
- * delivery channels). The guardian is intentionally left passive here: the
- * withdrawn card already reflects the expired state, so a fresh ping would be
- * noise.
- *
- * Best-effort by contract: the request is already resolved (CAS committed)
- * before this runs, so a failed notice or interaction release must never
- * surface as a sweep failure. Nothing here throws.
- */
-
-import type { CanonicalGuardianRequest } from "../memory/canonical-guardian-store.js";
-import { DAEMON_INTERNAL_ASSISTANT_ID } from "../runtime/assistant-scope.js";
-import { deliverChannelReply } from "../runtime/gateway-client.js";
-import * as pendingInteractions from "../runtime/pending-interactions.js";
-import { getLogger } from "../util/logger.js";
-import { resolveDeliverCallbackUrlForChannel } from "./guardian-channel-delivery.js";
-
-const log = getLogger("guardian-expiry-notifier");
-
-/**
- * Run the expiry side effects for a single canonical guardian request that the
- * sweep just transitioned to `expired`. Dispatches by kind; never throws.
- */
-export async function notifyExpiredGuardianRequest(
-  request: CanonicalGuardianRequest,
-): Promise<void> {
-  try {
-    switch (request.kind) {
-      case "tool_approval":
-        releaseExpiredInteraction(request);
-        return;
-      case "access_request":
-        await notifyRequesterOfExpiry(
-          request,
-          "Your access request expired before it was reviewed. " +
-            "Send a new message if you still need access.",
-        );
-        return;
-      case "tool_grant_request":
-        await notifyRequesterOfExpiry(
-          request,
-          `Your request to use "${request.toolName ?? "a tool"}" expired ` +
-            "before it was reviewed. Ask again if you still need it.",
-        );
-        return;
-      case "pending_question":
-        // Voice call sessions own their own lifecycle and timeout. By the time
-        // the canonical TTL lapses the call is long over and there is no
-        // durable requester channel to notify, so there is nothing to do.
-        return;
-      default:
-        return;
-    }
-  } catch (err) {
-    log.warn(
-      { err, requestId: request.id, kind: request.kind },
-      "Expiry side effects failed for canonical guardian request (non-fatal)",
-    );
-  }
-}
-
-/**
- * Release the in-memory pending interaction for an expired `tool_approval`.
- *
- * `tool_approval` is the one interaction-bound kind the periodic sweep can
- * reach (it carries a 30-minute `expiresAt`). In practice the canonical request
- * id does not key a *blocking* prompter interaction: ingress escalations — the
- * sole producer of this kind — register no interaction at all, and
- * PermissionPrompter confirmations are keyed by their own request id with their
- * own (far shorter) timeout. So this is a safe cleanup: it no-ops when nothing
- * is registered under the request id, and otherwise drops a waiter-less async
- * entry and emits `interaction_resolved` so clients clear the attention
- * indicator. `cancelled` is the documented runtime-termination/timeout outcome.
- */
-function releaseExpiredInteraction(request: CanonicalGuardianRequest): void {
-  const released = pendingInteractions.resolve(request.id, "cancelled");
-  if (released) {
-    log.info(
-      { requestId: request.id, kind: request.kind },
-      "Released pending interaction for expired guardian request",
-    );
-  }
-}
-
-/**
- * Deliver an expiry notice straight to the requester's chat.
- *
- * The sweep is timer-driven and holds no inbound reply callback URL, so this
- * mirrors the resolvers' off-channel (desktop) delivery path: post to the
- * callback-less `/deliver/<channel>` route. On Slack the notice is routed to
- * the requester's DM via their user id rather than the channel id, so it is
- * never posted into a shared channel. No-ops on channels without a deliverable
- * route (e.g. email, the in-app vellum surface) or when the requester chat is
- * unknown. Best-effort: a delivery failure is logged, never thrown.
- */
-async function notifyRequesterOfExpiry(
-  request: CanonicalGuardianRequest,
-  text: string,
-): Promise<void> {
-  const channel = request.sourceChannel ?? "";
-  const deliverUrl = resolveDeliverCallbackUrlForChannel(channel);
-  const requesterChatId =
-    request.requesterChatId ?? request.requesterExternalUserId ?? "";
-  const requesterExternalUserId = request.requesterExternalUserId ?? "";
-
-  if (!deliverUrl || !requesterChatId) {
-    return;
-  }
-
-  // On Slack, target the requester's DM (their `U…` user id) instead of the
-  // channel id so the expiry notice stays private. Other channels deliver to
-  // the requester chat directly.
-  const targetChatId =
-    channel === "slack" && requesterExternalUserId
-      ? requesterExternalUserId
-      : requesterChatId;
-
-  try {
-    await deliverChannelReply(deliverUrl, {
-      chatId: targetChatId,
-      text,
-      assistantId: DAEMON_INTERNAL_ASSISTANT_ID,
-    });
-    log.info(
-      { requestId: request.id, kind: request.kind, channel },
-      "Notified requester that guardian request expired",
-    );
-  } catch (err) {
-    log.warn(
-      { err, requestId: request.id, channel },
-      "Failed to notify requester of guardian request expiry (non-fatal)",
-    );
-  }
-}

package/src/cli/commands/memory/__tests__/worker.test.ts

@@ -1,302 +0,0 @@
-/**
- * Tests for the `assistant memory worker` CLI subgroup.
- *
- * Validates:
- *   - Subcommand registration (start, stop, status) under `memory worker`.
- *   - `status` reports running/not_running via PID-file liveness.
- *   - `stop` sends SIGTERM to a live worker and errors when none is running.
- *   - `start` refuses to spawn when a worker is already running, and reports
- *     the PID once the spawned process writes its PID file.
- */
-
-import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
-
-import { Command } from "commander";
-
-// ---------------------------------------------------------------------------
-// Mock state
-// ---------------------------------------------------------------------------
-
-let tmpDir: string;
-let pidPath: string;
-let logOutput: string[] = [];
-
-/** Records (pid, signal) pairs passed to the mocked process.kill. */
-let killCalls: Array<{ pid: number; signal: string | number }> = [];
-
-// ---------------------------------------------------------------------------
-// Mocks
-// ---------------------------------------------------------------------------
-
-mock.module("../../../../util/platform.js", () => ({
-  getMemoryWorkerPidPath: () => pidPath,
-}));
-
-const capture = (...args: unknown[]) => {
-  logOutput.push(args.map(String).join(" "));
-};
-const fakeLogger = {
-  info: capture,
-  warn: capture,
-  error: capture,
-  debug: () => {},
-};
-mock.module("../../../../util/logger.js", () => ({
-  getLogger: () => fakeLogger,
-  getCliLogger: () => fakeLogger,
-}));
-
-// ---------------------------------------------------------------------------
-// Import module under test (after mocks)
-// ---------------------------------------------------------------------------
-
-const { registerMemoryWorkerCommand } = await import("../worker.js");
-
-// ---------------------------------------------------------------------------
-// Test helpers
-// ---------------------------------------------------------------------------
-
-function buildProgram(): Command {
-  const program = new Command();
-  program.exitOverride();
-  program.configureOutput({
-    writeErr: () => {},
-    writeOut: () => {},
-  });
-  const memory = program.command("memory");
-  registerMemoryWorkerCommand(memory);
-  return program;
-}
-
-async function runCommand(
-  args: string[],
-): Promise<{ stdout: string; exitCode: number }> {
-  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
-  const originalStderrWrite = process.stderr.write.bind(process.stderr);
-  const stdoutChunks: string[] = [];
-
-  process.stdout.write = ((chunk: unknown) => {
-    stdoutChunks.push(typeof chunk === "string" ? chunk : String(chunk));
-    return true;
-  }) as typeof process.stdout.write;
-
-  process.stderr.write = (() => true) as typeof process.stderr.write;
-
-  process.exitCode = 0;
-
-  try {
-    const program = buildProgram();
-    await program.parseAsync(["node", "assistant", ...args]);
-  } catch {
-    if (process.exitCode === 0) process.exitCode = 1;
-  } finally {
-    process.stdout.write = originalStdoutWrite;
-    process.stderr.write = originalStderrWrite;
-  }
-
-  const exitCode = process.exitCode ?? 0;
-  process.exitCode = 0;
-
-  return { exitCode, stdout: stdoutChunks.join("") };
-}
-
-/**
- * Replace process.kill with a recording stub. `signal 0` is the liveness
- * probe: it resolves for `livePids` and throws ESRCH otherwise. Other signals
- * are recorded and no-oped so the test runner is never actually signalled.
- */
-function stubProcessKill(livePids: Set<number>): () => void {
-  const original = process.kill.bind(process);
-  killCalls = [];
-  process.kill = ((pid: number, signal?: string | number) => {
-    const sig = signal ?? 0;
-    if (sig === 0) {
-      if (livePids.has(pid)) return true;
-      const err = new Error("kill ESRCH") as NodeJS.ErrnoException;
-      err.code = "ESRCH";
-      throw err;
-    }
-    killCalls.push({ pid, signal: sig });
-    return true;
-  }) as typeof process.kill;
-  return () => {
-    process.kill = original;
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Setup
-// ---------------------------------------------------------------------------
-
-beforeEach(() => {
-  tmpDir = mkdtempSync(join(tmpdir(), "memory-worker-test-"));
-  pidPath = join(tmpDir, "memory-worker.pid");
-  logOutput = [];
-  killCalls = [];
-  process.exitCode = 0;
-});
-
-afterEach(() => {
-  rmSync(tmpDir, { recursive: true, force: true });
-});
-
-// ---------------------------------------------------------------------------
-// Subcommand registration
-// ---------------------------------------------------------------------------
-
-describe("subcommand registration", () => {
-  test("registers worker under memory with start/stop/status", () => {
-    const program = buildProgram();
-    const memory = program.commands.find((c) => c.name() === "memory");
-    expect(memory).toBeDefined();
-    const worker = memory!.commands.find((c) => c.name() === "worker");
-    expect(worker).toBeDefined();
-    const subcommandNames = worker!.commands.map((c) => c.name()).sort();
-    expect(subcommandNames).toEqual(["start", "status", "stop"]);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// status
-// ---------------------------------------------------------------------------
-
-describe("memory worker status", () => {
-  test("reports not_running when no PID file exists", async () => {
-    const { exitCode, stdout } = await runCommand([
-      "memory",
-      "worker",
-      "status",
-      "--json",
-    ]);
-    expect(exitCode).toBe(0);
-    expect(JSON.parse(stdout)).toEqual({ status: "not_running" });
-  });
-
-  test("reports running when PID file points at a live process", async () => {
-    writeFileSync(pidPath, String(process.pid));
-    const restore = stubProcessKill(new Set([process.pid]));
-    try {
-      const { exitCode, stdout } = await runCommand([
-        "memory",
-        "worker",
-        "status",
-        "--json",
-      ]);
-      expect(exitCode).toBe(0);
-      expect(JSON.parse(stdout)).toEqual({
-        status: "running",
-        pid: process.pid,
-      });
-    } finally {
-      restore();
-    }
-  });
-
-  test("treats a stale PID file as not_running and cleans it up", async () => {
-    writeFileSync(pidPath, "999999");
-    const restore = stubProcessKill(new Set());
-    try {
-      const { exitCode, stdout } = await runCommand([
-        "memory",
-        "worker",
-        "status",
-        "--json",
-      ]);
-      expect(exitCode).toBe(0);
-      expect(JSON.parse(stdout)).toEqual({ status: "not_running" });
-      expect(existsSync(pidPath)).toBe(false);
-    } finally {
-      restore();
-    }
-  });
-});
-
-// ---------------------------------------------------------------------------
-// stop
-// ---------------------------------------------------------------------------
-
-describe("memory worker stop", () => {
-  test("errors with exit 1 when no worker is running", async () => {
-    const { exitCode, stdout } = await runCommand([
-      "memory",
-      "worker",
-      "stop",
-      "--json",
-    ]);
-    expect(exitCode).toBe(1);
-    expect(JSON.parse(stdout)).toMatchObject({ ok: false });
-  });
-
-  test("sends SIGTERM to a running worker", async () => {
-    writeFileSync(pidPath, String(process.pid));
-    const restore = stubProcessKill(new Set([process.pid]));
-    try {
-      const { exitCode, stdout } = await runCommand([
-        "memory",
-        "worker",
-        "stop",
-        "--json",
-      ]);
-      expect(exitCode).toBe(0);
-      expect(JSON.parse(stdout)).toEqual({ ok: true, pid: process.pid });
-      expect(killCalls).toContainEqual({
-        pid: process.pid,
-        signal: "SIGTERM",
-      });
-    } finally {
-      restore();
-    }
-  });
-});
-
-// ---------------------------------------------------------------------------
-// start
-// ---------------------------------------------------------------------------
-
-describe("memory worker start", () => {
-  test("refuses to start when a worker is already running", async () => {
-    writeFileSync(pidPath, String(process.pid));
-    const restore = stubProcessKill(new Set([process.pid]));
-    try {
-      const { exitCode, stdout } = await runCommand([
-        "memory",
-        "worker",
-        "start",
-        "--json",
-      ]);
-      expect(exitCode).toBe(1);
-      expect(JSON.parse(stdout)).toMatchObject({
-        ok: false,
-        pid: process.pid,
-      });
-    } finally {
-      restore();
-    }
-  });
-
-  test("spawns the worker and reports the PID it writes", async () => {
-    const restore = stubProcessKill(new Set());
-    const originalSpawn = Bun.spawn;
-    // Simulate the spawned worker writing its PID file on startup.
-    (Bun as { spawn: typeof Bun.spawn }).spawn = (() => {
-      writeFileSync(pidPath, "424242");
-      return { unref: () => {}, pid: 424242 };
-    }) as unknown as typeof Bun.spawn;
-    try {
-      const { exitCode, stdout } = await runCommand([
-        "memory",
-        "worker",
-        "start",
-        "--json",
-      ]);
-      expect(exitCode).toBe(0);
-      expect(JSON.parse(stdout)).toMatchObject({ ok: true, pid: 424242 });
-    } finally {
-      (Bun as { spawn: typeof Bun.spawn }).spawn = originalSpawn;
-      restore();
-    }
-  });
-});