@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/runtime/trust-class.ts

@@ -0,0 +1,121 @@
+/**
+ * Trust classification for an inbound actor — the single source of truth for
+ * both the {@link TrustClass} type and the Zod enum ({@link trustClassSchema})
+ * that validates it in persisted message metadata.
+ *
+ * Kept as a leaf module (imports only `zod`) so the runtime trust layer and the
+ * persistence schema can share one definition without a circular import.
+ *
+ * - `'guardian'`: The sender matches the active guardian binding for this
+ *   (assistant, channel). Guardians have full control-plane access and
+ *   self-approve tool invocations.
+ * - `'trusted_contact'`: The sender is an active contact with a channel
+ *   (not the guardian). Trusted contacts can invoke tools but require
+ *   guardian approval for sensitive operations.
+ * - `'unverified_contact'`: The sender matches a contact channel whose
+ *   status is `pending` or `unverified` — known to the guardian but not yet
+ *   verified. Treated identically to `trusted_contact` for every downstream
+ *   capability/tool/approval decision; the distinction is admission-only.
+ * - `'unknown'`: The sender has no contact record, no identity could be
+ *   established, or the sender is a blocked/revoked contact. Unknown
+ *   actors are fail-closed with no escalation path.
+ */
+
+import { z } from "zod";
+
+export const trustClassSchema = z.enum([
+  "guardian",
+  "trusted_contact",
+  "unverified_contact",
+  "unknown",
+]);
+
+export type TrustClass = z.infer<typeof trustClassSchema>;
+
+/**
+ * Whether a trust class names a known non-guardian contact — the
+ * `trusted_contact` / `unverified_contact` pair whose admission-only
+ * equivalence is documented on {@link trustClassSchema}.
+ *
+ * Accepts a raw string (not just `TrustClass`) because several call sites
+ * classify trust classes read back from persisted turn metadata, which may
+ * carry legacy or foreign values; anything outside the pair — including
+ * `undefined` — is not a contact.
+ */
+export function isContactTrustClass(
+  trustClass: string | undefined,
+): trustClass is "trusted_contact" | "unverified_contact" {
+  return (
+    trustClass === "trusted_contact" || trustClass === "unverified_contact"
+  );
+}
+
+/**
+ * Persona-facing view of a trust class, precomputed as booleans because the
+ * system-prompt mustache renderer only does truthy section gating, not string
+ * comparison. Exactly one flag is true per class; `trustClass` is the resolved
+ * class the flags were derived from.
+ */
+export interface PersonaTrustFlags {
+  trustClass: TrustClass;
+  isGuardian: boolean;
+  isTrustedContact: boolean;
+  isStranger: boolean;
+}
+
+/**
+ * Derive the persona/prompt-gating flags for an actor's trust class — the one
+ * home for how persona/prompt surfaces (notably `users/default.md`, the
+ * persona rendered for non-guardian actors) classify who is being spoken to.
+ *
+ * - An absent class (unresolved actor) derives as `stranger`. This is
+ *   deliberately NOT `resolveTrustClass()`: that helper fail-safes an
+ *   unresolved turn to `guardian` under the local auth-bypass so control-plane
+ *   capability gates don't block local development. A data-disclosure boundary
+ *   needs the opposite default — fail closed, so a turn that never resolved an
+ *   actor still renders the guardrail rather than a guardian exemption.
+ * - `unverified_contact` derives identically to `trusted_contact`, making the
+ *   admission-only equivalence documented on {@link trustClassSchema}
+ *   executable in one place.
+ * - The switch is exhaustive with no default: adding a `TrustClass` member is a
+ *   compile error here, forcing a deliberate persona decision for the new
+ *   class.
+ *
+ * Scope: prompt/persona rendering only — the *data-disclosure* boundary. Its
+ * complement, identity/verification hygiene, is `promptTrustGuidance` in
+ * `resolveCapabilities()` (rendered by
+ * `plugins/defaults/turn-context/unified-turn-context.ts`); capability and tool
+ * gating must keep using `resolveCapabilities()` / `resolveTrustClass()`.
+ */
+export function derivePersonaTrustFlags(
+  trustClass: TrustClass | undefined,
+): PersonaTrustFlags {
+  const resolved: TrustClass = trustClass ?? "unknown";
+  switch (resolved) {
+    case "guardian": {
+      return {
+        trustClass: resolved,
+        isGuardian: true,
+        isTrustedContact: false,
+        isStranger: false,
+      };
+    }
+    case "trusted_contact":
+    case "unverified_contact": {
+      return {
+        trustClass: resolved,
+        isGuardian: false,
+        isTrustedContact: true,
+        isStranger: false,
+      };
+    }
+    case "unknown": {
+      return {
+        trustClass: resolved,
+        isGuardian: false,
+        isTrustedContact: false,
+        isStranger: true,
+      };
+    }
+  }
+}

package/src/runtime/trust-verdict-consumer.ts

@@ -105,6 +105,13 @@ export function trustContextFromVerdict(
     context.memberPolicy = member.policy;
   }
 
+  // Interaction telemetry is gateway-owned: carry the verdict's count straight
+  // through so turn assembly reads it from the verdict rather than the local
+  // assistant DB.
+  if (verdict.interactionCount !== undefined) {
+    context.requesterInteractionCount = verdict.interactionCount;
+  }
+
   return context;
 }
 
@@ -208,10 +215,6 @@ function memberRecordFromVerdict(
     address: verdict.address ?? "",
     isPrimary: false,
     externalChatId: verdict.externalChatId ?? null,
-    inviteId: null,
-    lastSeenAt: null,
-    interactionCount: 0,
-    lastInteraction: null,
     updatedAt: null,
     createdAt: 0,
   };
@@ -224,8 +227,6 @@ function memberRecordFromVerdict(
     displayName: member.displayName ?? "",
     notes: null,
     role,
-    lastInteraction: null,
-    interactionCount: 0,
     createdAt: 0,
     updatedAt: 0,
     contactType: "human",

package/src/schedule/__tests__/run-script.test.ts

@@ -0,0 +1,21 @@
+/**
+ * `runScript` injects the schedule's ids into the spawned command's env so a
+ * saved command can reference its own dir, e.g.
+ * `cd "$VELLUM_WORKSPACE_DIR/schedules/$__SCHEDULE_ID" && bun poll.ts`.
+ */
+
+import { tmpdir } from "node:os";
+import { describe, expect, test } from "bun:test";
+
+import { runScript } from "../run-script.js";
+
+describe("runScript schedule env injection", () => {
+  test("injects __SCHEDULE_ID and __SCHEDULE_RUN_ID, expanded by the shell", async () => {
+    const result = await runScript(
+      'echo "id=$__SCHEDULE_ID run=$__SCHEDULE_RUN_ID"',
+      { cwd: tmpdir(), scheduleId: "sched-abc", scheduleRunId: "run-xyz" },
+    );
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.trim()).toBe("id=sched-abc run=run-xyz");
+  });
+});

package/src/schedule/__tests__/worker-control.test.ts

@@ -0,0 +1,241 @@
+/**
+ * Tests for the schedule worker process control surface.
+ *
+ * Focuses on the readiness wait (which gates whether `assistant schedules
+ * worker start` reports success and flips `schedules.worker.enabled`) and the
+ * PID-file liveness probe, mirroring the memory worker's worker-control tests.
+ */
+
+import { 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 * as realLogger from "../../util/logger.js";
+import * as realPlatform from "../../util/platform.js";
+
+let tmpDir: string;
+let pidPath: string;
+
+mock.module("../../util/platform.js", () => ({
+  ...realPlatform,
+  getScheduleWorkerPidPath: () => pidPath,
+}));
+
+const noopLogger = {
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  debug: () => {},
+};
+mock.module("../../util/logger.js", () => ({
+  ...realLogger,
+  getLogger: () => noopLogger,
+  getCliLogger: () => noopLogger,
+  getCurrentLogFilePath: () => join(tmpDir, "schedule-worker-test.log"),
+}));
+
+const {
+  spawnScheduleWorkerProcess,
+  ScheduleWorkerSpawnError,
+  probeScheduleWorker,
+  stopScheduleWorkerProcess,
+} = await import("../worker-control.js");
+
+function stubProcessKill(
+  livePids: Set<number>,
+  permissionErrorPids: Set<number> = new Set(),
+): () => void {
+  const original = process.kill.bind(process);
+  process.kill = ((pid: number, signal?: string | number) => {
+    if ((signal ?? 0) !== 0) {
+      return true;
+    }
+    if (permissionErrorPids.has(pid)) {
+      const err = new Error("kill EPERM") as NodeJS.ErrnoException;
+      err.code = "EPERM";
+      throw err;
+    }
+    if (livePids.has(pid)) {
+      return true;
+    }
+    const err = new Error("kill ESRCH") as NodeJS.ErrnoException;
+    err.code = "ESRCH";
+    throw err;
+  }) as typeof process.kill;
+  return () => {
+    process.kill = original;
+  };
+}
+
+function stubBunSpawn(
+  makeChild: () => {
+    unref: () => void;
+    kill: () => void;
+    pid: number;
+    exited?: Promise<unknown>;
+  },
+): () => void {
+  const original = Bun.spawn;
+  (Bun as { spawn: typeof Bun.spawn }).spawn = (() =>
+    makeChild()) as unknown as typeof Bun.spawn;
+  return () => {
+    (Bun as { spawn: typeof Bun.spawn }).spawn = original;
+  };
+}
+
+function neverExits(): Promise<unknown> {
+  return new Promise(() => {});
+}
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "schedule-worker-control-test-"));
+  pidPath = join(tmpDir, "schedule-worker.pid");
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("spawnScheduleWorkerProcess", () => {
+  test("returns the PID when the worker writes its file immediately", async () => {
+    const restore = stubBunSpawn(() => {
+      writeFileSync(pidPath, "4242");
+      return {
+        unref: () => {},
+        kill: () => {},
+        pid: 4242,
+        exited: neverExits(),
+      };
+    });
+    try {
+      const result = await spawnScheduleWorkerProcess({
+        pidWaitTimeoutMs: 1_000,
+        pidPollIntervalMs: 10,
+      });
+      expect(result).toEqual({ pid: 4242, alreadyRunning: false });
+    } finally {
+      restore();
+    }
+  });
+
+  test("fails fast when the child exits during startup", async () => {
+    let killed = false;
+    const restore = stubBunSpawn(() => ({
+      unref: () => {},
+      kill: () => {
+        killed = true;
+      },
+      pid: 99,
+      exited: Promise.resolve(1),
+    }));
+    try {
+      await expect(
+        spawnScheduleWorkerProcess({
+          pidWaitTimeoutMs: 10_000,
+          pidPollIntervalMs: 10,
+          terminateOnTimeout: true,
+        }),
+      ).rejects.toBeInstanceOf(ScheduleWorkerSpawnError);
+      expect(killed).toBe(false);
+    } finally {
+      restore();
+    }
+  });
+
+  test("terminates a still-alive child on timeout when asked", async () => {
+    let killed = false;
+    const restore = stubBunSpawn(() => ({
+      unref: () => {},
+      kill: () => {
+        killed = true;
+      },
+      pid: 55,
+      exited: neverExits(),
+    }));
+    try {
+      await expect(
+        spawnScheduleWorkerProcess({
+          pidWaitTimeoutMs: 150,
+          pidPollIntervalMs: 20,
+          terminateOnTimeout: true,
+        }),
+      ).rejects.toBeInstanceOf(ScheduleWorkerSpawnError);
+      expect(killed).toBe(true);
+    } finally {
+      restore();
+    }
+  });
+
+  test("reuses an already-running worker without spawning", async () => {
+    writeFileSync(pidPath, String(process.pid));
+    let spawned = false;
+    const restore = stubBunSpawn(() => {
+      spawned = true;
+      return { unref: () => {}, kill: () => {}, pid: 1, exited: neverExits() };
+    });
+    try {
+      const result = await spawnScheduleWorkerProcess({
+        pidWaitTimeoutMs: 100,
+      });
+      expect(result).toEqual({ pid: process.pid, alreadyRunning: true });
+      expect(spawned).toBe(false);
+    } finally {
+      restore();
+    }
+  });
+});
+
+describe("probeScheduleWorker", () => {
+  test("reports not_running when no PID file exists", () => {
+    expect(probeScheduleWorker()).toEqual({ status: "not_running" });
+  });
+
+  test("cleans up a stale PID file pointing at a dead process", () => {
+    writeFileSync(pidPath, "999999");
+    const restore = stubProcessKill(new Set());
+    try {
+      expect(probeScheduleWorker()).toEqual({ status: "not_running" });
+    } finally {
+      restore();
+    }
+  });
+
+  test("reports running (not throws) when the process exists but is not signalable (EPERM)", () => {
+    writeFileSync(pidPath, "4321");
+    const restore = stubProcessKill(new Set(), new Set([4321]));
+    try {
+      expect(probeScheduleWorker()).toEqual({ status: "running", pid: 4321 });
+    } finally {
+      restore();
+    }
+  });
+});
+
+describe("stopScheduleWorkerProcess", () => {
+  test("is a no-op when the worker is not running", () => {
+    expect(stopScheduleWorkerProcess()).toEqual({ status: "not_running" });
+  });
+
+  test("signals a running worker and reports its prior state", () => {
+    writeFileSync(pidPath, "4321");
+    const signalled: Array<[number, string | number | undefined]> = [];
+    const original = process.kill.bind(process);
+    process.kill = ((pid: number, signal?: string | number) => {
+      if ((signal ?? 0) === 0) {
+        return true;
+      } // liveness probe
+      signalled.push([pid, signal]);
+      return true;
+    }) as typeof process.kill;
+    try {
+      expect(stopScheduleWorkerProcess()).toEqual({
+        status: "running",
+        pid: 4321,
+      });
+      expect(signalled).toEqual([[4321, "SIGTERM"]]);
+    } finally {
+      process.kill = original;
+    }
+  });
+});

package/src/schedule/run-script.ts

@@ -32,10 +32,15 @@ export interface ScriptResult {
  */
 export async function runScript(
   command: string,
-  options?: { timeoutMs?: number; cwd?: string; scheduleRunId?: string },
+  options: {
+    scheduleRunId: string;
+    scheduleId: string;
+    timeoutMs?: number;
+    cwd?: string;
+  },
 ): Promise<ScriptResult> {
-  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const cwd = options?.cwd ?? getWorkspaceDir();
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const cwd = options.cwd ?? getWorkspaceDir();
 
   log.info({ command, cwd, timeoutMs }, "Running script");
 
@@ -45,9 +50,11 @@ export async function runScript(
     stderr: "pipe",
     env: {
       ...buildSanitizedEnv(),
-      ...(options?.scheduleRunId
-        ? { __SCHEDULE_RUN_ID: options.scheduleRunId }
-        : {}),
+      // __SCHEDULE_ID lets a saved command find its own dir; __SCHEDULE_RUN_ID
+      // is the per-firing id (cost attribution). Required, so a script run is
+      // always attributable and can locate its dir.
+      __SCHEDULE_RUN_ID: options.scheduleRunId,
+      __SCHEDULE_ID: options.scheduleId,
     },
   });
 

package/src/schedule/schedule-usage-store.ts

@@ -29,6 +29,7 @@ export function getScheduleUsageSummaries({
     selectExpression: "schedule_attr_runs.job_id",
   });
   const rows = rawAll<ScheduleUsageSummaryRow>(
+    "scheduleUsage:getSummaries",
     /*sql*/ `
     WITH run_counts AS (
       SELECT